Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add AdvancedSearch typings #48

Merged
merged 2 commits into from
Jan 8, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions components/index.d.ts
Original file line number Diff line number Diff line change
@@ -156,8 +156,15 @@ export { default as SearchField } from './lib/SearchField';
export { default as ConflictDetectionBanner } from './lib/ConflictDetectionBanner';
export {
AdvancedSearch,
AdvancedSearchProps,
AdvancedSearchRow,
AdvancedSearchRowFormatter,
useAdvancedSearch,
defaultQueryBuilder as defaultAdvancedSearchQueryBuilder,
BOOLEAN_OPERATORS as ADVANCED_SEARCH_BOOLEAN_OPERATORS,
MATCH_OPTIONS as ADVANCED_SEARCH_MATCH_OPTIONS,
FIELD_NAMES as ADVANCED_SEARCH_FIELD_NAMES,
DEFAULT_SEARCH_OPTION as ADVANCED_SEARCH_DEFAULT_SEARCH_OPTION,
} from './lib/AdvancedSearch';

/* specific use */
81 changes: 81 additions & 0 deletions components/lib/AdvancedSearch/AdvancedSearch.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
import { ReactNode } from 'react';
import { ValueOf } from 'type-fest';
import { BOOLEAN_OPERATORS } from '.';

type RowFormatter = (
searchOption: string,
query: string,
comparator: string,
bool: ValueOf<typeof BOOLEAN_OPERATORS>,
) => string;
type Row = {
bool: ValueOf<typeof BOOLEAN_OPERATORS>;
query: string;
searchOption: string;
};

export interface AdvancedSearchProps {
/** Render function. Accepts `resetRows` to clear `AdvancedSearch` state */
children?: (props: { resetRows: () => void }) => ReactNode;
/** One of the options in `searchOptions` that will be selected by default in all rows */
defaultSearchOptionValue?: string;
/** Object with shape `{ query, option }` - will be used to populate first row with default values */
firstRowInitialSearch?: { query?: string; option?: string } | null;
/** Show/hide search match option dropdown */
hasMatchSelection?: boolean;
/** Controls whether `Query` search option should be appended to search options list */
hasQueryOption?: boolean;
/** Callback fired when the user clicks the cancel button */
onCancel: () => void;
/** Callback fired when search is performed. Called with two arguments:
* - `query`: formatted query string
* - `rows`: array of non-empty rows
*/
onSearch: (query: string, rows: Row[]) => void;
/** Controls the visibility of the `<AdvancedSearch>` */
open?: boolean;
/** Function to construct the search query */
queryBuilder?: (rows: Row[], rowFormatter: RowFormatter) => string;
/** Function that combines boolean, query, and search option of each row. Used by `queryBuilder` to join rows */
rowFormatter?: RowFormatter;
/** Custom function to parse a query string into rows */
queryToRow?: (input: { query: string }) => Row[];
/** Search options; query will be automatically added as the first option */
searchOptions: {
label: string;
value: string;
id?: string;
}[];
}

/**
* Provides advanced search functionality - user-friendly ability to construct a complex query with boolean conditions.
*
* @example
* ```
* // in component body
* const searchOptions = [{
* id: 'keyword',
* label: 'Keyword',
* value: 'keyword',
* }, {
* id: 'name',
* label: 'Name',
* value: 'name',
* }];
*
* const keywordOption = 'keyword';
*
* const firstRowInitialSearch = {};
*
* <AdvancedSearch
* open={isOpen}
* searchOptions={searchOptions}
* defaultSearchOptionValue={keywordOption}
* firstRowInitialSearch={firstRowInitialSearch}
* onSearch={handleSearch}
* onCancel={handleCancel}
* />
* ```
*/
export default function AdvancedSearch(props: AdvancedSearchProps): ReactNode;
20 changes: 20 additions & 0 deletions components/lib/AdvancedSearch/constants.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
export const FIELD_NAMES: {
BOOL: 'bool';
QUERY: 'query';
MATCH: 'match';
SEARCH_OPTION: 'searchOption';
};
export const ROW_COUNT: 6;
export const BOOLEAN_OPERATORS: {
AND: 'and';
OR: 'or';
NOT: 'not';
};
export const QUERY_OPTION_VALUE: 'advancedSearch';
export const DEFAULT_SEARCH_OPTION: 'keyword';
export const MATCH_OPTIONS: {
EXACT_PHRASE: 'exactPhrase';
CONTAINS_ALL: 'containsAll';
STARTS_WITH: 'startsWith';
CONTAINS_ANY: 'containsAny';
};
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
declare const useAdvancedSearch: any;
export default useAdvancedSearch;
export { default } from './useAdvancedSearch';
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
import { AdvancedSearchProps, Row } from '../../AdvancedSearch';

export default function useAdvancedSearch(opts: {
/** One of the options in `searchOptions` that will be selected by default in all rows */
defaultSearchOptionValue: string;
/** Object with shape `{ query, option }` - will be used to populate first row with default values */
firstRowInitialSearch: AdvancedSearchProps['firstRowInitialSearch'];
/** Callback fired when the user clicks the cancel button */
onCancel?: () => void;
/** Callback fired when search is performed. Called with two arguments:
* - `query`: formatted query string
* - `rows`: array of non-empty rows
*/
onSearch?: (query: string, rows: Row[]) => void;
/** Function to construct the search query */
queryBuilder?: AdvancedSearchProps['queryBuilder'];
/** Function that combines boolean, query, and search option of each row. Used by `queryBuilder` to join rows */
rowFormatter?: AdvancedSearchProps['rowFormatter'];
/** Custom function to parse a query string into rows */
queryToRow?: AdvancedSearchProps['queryToRow'];
/** Search options; query will be automatically added as the first option */
searchOptions: AdvancedSearchProps['searchOptions'];
/** Controls whether `Query` search option should be appended to search options list */
hasQueryOption?: boolean;
/** Controls the visibility of the `<AdvancedSearch>` */
open?: boolean;
}): {
handleCancel: () => void;
handleSearch: () => void;
onChange: (index: number, key: string, value: string) => void;
resetRows: () => void;
rowState: Row[];
searchOptionsWithQuery: AdvancedSearchProps['searchOptions'];
showEmptyFirstRowMessage: boolean;
filledRows: Row[];
query: string;
};
13 changes: 10 additions & 3 deletions components/lib/AdvancedSearch/index.d.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
export const AdvancedSearch: any;
export const defaultQueryBuilder: any;
export const BOOLEAN_OPERATORS: any;
export {
default as AdvancedSearch,
AdvancedSearchProps,
Row as AdvancedSearchRow,
RowFormatter as AdvancedSearchRowFormatter,
} from './AdvancedSearch';
export { default as useAdvancedSearch } from './hooks/useAdvancedSearch';
export { default as defaultQueryBuilder } from './utilities/defaultQueryBuilder';

export { FIELD_NAMES, BOOLEAN_OPERATORS, MATCH_OPTIONS, DEFAULT_SEARCH_OPTION } from './constants';
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
import { Row, RowFormatter } from '../AdvancedSearch';

export default function defaultQueryBuilder(rows: Row[], rowFormatter: RowFormatter[]): string;