@workday/canvas-kit-react
Version:
The parent module that contains all Workday Canvas Kit React components
106 lines • 4.37 kB
TypeScript
import { Model } from '@workday/canvas-kit-react/common';
import { useListModel } from './useListModel';
export interface LoadReturn<T> {
items: T[];
total?: number;
}
export interface LoadParams {
pageNumber: number;
pageSize: number;
filter: CollectionLoader['filter'];
sorter: CollectionLoader['sorter'];
}
export interface AsyncCollectionConfig<T, M extends Model<any, any>> {
/**
* The desired results per page.
*/
pageSize: number;
/**
* The total items in the collection. If you do not have this information before making an API
* call, leave it blank and it will default to `0` and be updated when `load` comes back with
* results.
* @default 0
*/
total?: number;
/**
* This function acts like a guard similar to model events. If you provide this function and it
* returns `false`, the `load` call from the loader will be cancelled. Be aware, this function can
* cause a loader to not function properly. You will need to call `loader.load(pageNumber)` on
* your own if a valid load event is cancelled. An example of using this function is in
* {@link useComboboxLoader} where the load calls are only allowed when the menu is open.
*/
shouldLoad?(
/**
* Parameters that are being sent to the `load` function
*/
params: LoadParams,
/**
* State coming from the model
*/
prevState: M['state']): boolean;
/**
* A `load` callback function provides an easier way to hook up loader requests for data to an
* API. It will be called when the user is ready for more of the virtual data set. The `load`
* function will be called when:
* - The list UI initially loads. It will request as many pages as necessary to render enough
* items in the viewport
* - The user is scrolling the list and has run out of cached data
* - The user is using the keyboard to navigate the list and has run out of cached data
* - A filter or sorter value has changed and the cached data is now invalid
* - `loader.load` was called by the developer, manually requesting a page number
*/
load(params: LoadParams): LoadReturn<T> | Promise<LoadReturn<T>>;
}
export interface CollectionLoader {
filter: string | Record<string, string>;
updateFilter(value: string): void;
sorter: string | Record<string, string>;
updateSorter(value: string): void;
isLoading: boolean;
load(pageNumber?: number): void;
}
export declare function getPageNumber(index: number, pageSize: number): number;
/**
*
* @param start The start index of the virtual window
* @param end The end index of the virtual window
* @param pageSize Expected load page size
* @param items Sparse array of all loaded items
* @param overScan How many items ahead we want to look ahead to trigger loading. Unloaded items
* that are this many items outside the current start and end numbers will trigger a loading of
* a page
*/
export declare function getPagesToLoad<T>(start: number, end: number, pageSize: number, items: T[], overScan?: number): number[];
/**
* Create a data loader and a model. The list loader should be used on virtual data sets with
* possibly large amounts of data. The model should be passed to a collection component. The loader
* can be used to manipulate filters, sorters, and clear cache.
*
* A simple loader using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) could
* look like the following:
*
* ```ts
* const {model, loader} = useListLoader(
* {
* total: 1000,
* pageSize: 20,
* async load({pageNumber, pageSize}) {
* return fetch('/myUrl')
* .then(response => response.json())
* .then(response => {
* return {total: response.total, items: response.items};
* });
* },
* },
* useListModel
* );
* ```
*
* @param config Config that contains the loader config and the model config
* @param modelHook A model hook that describes which model should be returned.
*/
export declare function useListLoader<T, M extends ((...args: any[]) => any) & Omit<typeof useListModel, 'Context'>>(config: AsyncCollectionConfig<T, ReturnType<M>> & M['TConfig'], modelHook: M): {
model: ReturnType<M>;
loader: CollectionLoader;
};
//# sourceMappingURL=useListLoader.d.ts.map