@future-widget-lab/ui-filters
Version:
A set of primitives for handling filters through search parameters in React applications.
336 lines (335 loc) • 10.6 kB
TypeScript
import type { AnyFilterInput, Commitable, CommitFunction, Filters } from '../../types/filters.type';
import type { FilterInput } from '../../types/filters.type';
import { DeserializeFiltersOptions } from '../../helpers/deserialize-filters/deserialize-filters.helper';
export type AddFilterValueOptions = Commitable<{
/**
* @description
* The new filter value to add.
*/
input: FilterInput | Array<FilterInput>;
/**
* A hook that is fired before the value is added to the collection.
*
* Consumers can use this to perform any kind of side-effects or validation.
*/
onBeforeAdd?: (input: FilterInput) => void;
/**
* A hook that is fired after the value is added to the collection.
*
* Consumers can use this to perform any kind of side-effects.
*/
onAfterAdd?: (input: FilterInput) => void;
}>;
export type RemoveFilterValueOptions = Commitable<{
/**
* @description
* The filter value to remove.
*/
input: FilterInput | Array<FilterInput>;
}>;
export type SetFilterValueOptions = Commitable<{
/**
* @description
* The new filter value to set.
*/
input: AnyFilterInput | Array<AnyFilterInput>;
}>;
export type DestroyFilterOptions = Commitable<{
/**
* @description
* The filter value to destroy.
*/
name: string | Array<string>;
}>;
export type DestroyFiltersOptions = Commitable<{}>;
export type FiltersContext = {
/**
* @description
* Use this helper to add a new filter value for the specified filter name.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams] = useSearchParams();
*
* const commit = (q: string) => {
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* addFilterValue({ name: 'bankingAccountIds', value: '550e8400-e29b-41d4-a716-446655440000', commit });
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams] = useSearchParams();
*
* const commit = (q: string) => {
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* addFilterValue({ name: 'date', value: { 'start':'11-27-2023', 'end':'12-27-2023', 'dateRangeName': 'Last30Days', 'timezone':'local' }, commit });
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams] = useSearchParams();
*
* const commit = (q: string) => {
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* addFilterValue({ name: FilterName.BankingAccountIds, value: bankingAccountId, commit });
*/
addFilterValue: (options: AddFilterValueOptions) => void | Promise<void>;
/**
* @description
* Use this helper to remove a value from the given filter.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* removeFilterValue({ name: 'bankingAccountIds', value: '550e8400-e29b-41d4-a716-446655440000', commit });
*/
removeFilterValue: (options: RemoveFilterValueOptions) => void | Promise<void>;
/**
* @description
* Use this helper to set the value(s) of a given filter.
*
* - If `value` is `null`, `undefined`, or an empty array, the filter is removed.
* - If `value` is a single item, it replaces the existing filter values.
* - If `value` is an array, all existing filter values are cleared before adding the new ones.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* setFilterValue({ name: 'bankingAccountIds', value: '550e8400-e29b-41d4-a716-446655440000', commit });
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* setFilterValue({ name: 'bankingAccountIds', value: null, commit });
*/
setFilterValue: (options: SetFilterValueOptions) => Promise<void>;
/**
* @description
* Use this helper to remove a filter and its associated values from the filters collection.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* destroyFilter({ name: 'cart-items', commit });
*/
destroyFilter: (options: DestroyFilterOptions) => void | Promise<void>;
/**
* @description
* Use this helper to remove all the filters collection.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* setSearchParams(new URLSearchParams());
* };
*
* destroyFilters({ commit });
*/
destroyFilters: (options?: DestroyFiltersOptions) => void | Promise<void>;
/**
* @description
* Use this helper to retrieve the current values of a given filter.
*
* Defaults to an empty array if no filter is found.
*
* @example
* getFilterValues('bankingAccountIds');
*
* getFilterValues('date');
*
* getFilterValues('searchTerm');
*/
getFilterValues: <TData>(name: string) => Array<TData>;
};
export type FiltersContextProviderProps = Pick<DeserializeFiltersOptions, 'deserializer' | 'onBeforeDeserializer' | 'onAfterDeserializer' | 'onDeserializerError'> & {
/**
* @description
* The search parameters that should be used to retrieve the filters from.
*/
searchParams: URLSearchParams;
/**
* @description
* The search parameter name where the filters collection will be stored.
*
* Defaults to `q` if not present.
*/
searchParamName?: string;
/**
* @description
* Use this helper function to create a valid search param value given the filters collection.
*
* Defaults to flatted's `stringify` if not present (See https://www.npmjs.com/package/flatted).
*/
serializer?: (filters: Filters) => string;
/**
* @description
*
* A commit function is the equivalent of doing `transaction.commit()`;
*
* When passed at the provider's level it will become the default if no `commit` is passed explicitly to any of the exposed helpers.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* <FiltersProvider searchParams={searchParams} commit={commit}>
* <YourComponent/>
* </FiltersProvider>
*/
commit?: CommitFunction;
};
export declare const FiltersProvider: import("react").FC<Pick<DeserializeFiltersOptions, "deserializer" | "onBeforeDeserializer" | "onAfterDeserializer" | "onDeserializerError"> & {
/**
* @description
* The search parameters that should be used to retrieve the filters from.
*/
searchParams: URLSearchParams;
/**
* @description
* The search parameter name where the filters collection will be stored.
*
* Defaults to `q` if not present.
*/
searchParamName?: string;
/**
* @description
* Use this helper function to create a valid search param value given the filters collection.
*
* Defaults to flatted's `stringify` if not present (See https://www.npmjs.com/package/flatted).
*/
serializer?: (filters: Filters) => string;
/**
* @description
*
* A commit function is the equivalent of doing `transaction.commit()`;
*
* When passed at the provider's level it will become the default if no `commit` is passed explicitly to any of the exposed helpers.
*
* @example
* import { useSearchParams } from 'react-router';
*
* const [searchParams, setSearchParams] = useSearchParams();
*
* const commit: CommitFunction = (q) => {
* if (!q) {
* setSearchParams(new URLSearchParams());
*
* return;
* }
*
* setSearchParams((previousSearchParams) => {
* previousSearchParams.set('q', q!);
*
* return previousSearchParams;
* });
* };
*
* <FiltersProvider searchParams={searchParams} commit={commit}>
* <YourComponent/>
* </FiltersProvider>
*/
commit?: CommitFunction;
} & {
children: import("react").ReactNode | import("react").ReactNode[] | ((props: FiltersContext) => React.ReactNode | Array<React.ReactNode>);
}>, useFilters: () => FiltersContext;