diff --git a/components/index.d.ts b/components/index.d.ts index d6f7528..791a0b7 100644 --- a/components/index.d.ts +++ b/components/index.d.ts @@ -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 */ diff --git a/components/lib/AdvancedSearch/AdvancedSearch.d.ts b/components/lib/AdvancedSearch/AdvancedSearch.d.ts new file mode 100644 index 0000000..b663061 --- /dev/null +++ b/components/lib/AdvancedSearch/AdvancedSearch.d.ts @@ -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, +) => string; +type Row = { + bool: ValueOf; + 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 `` */ + 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 = {}; + * + * + * ``` + */ +export default function AdvancedSearch(props: AdvancedSearchProps): ReactNode; diff --git a/components/lib/AdvancedSearch/constants.d.ts b/components/lib/AdvancedSearch/constants.d.ts new file mode 100644 index 0000000..80c7c78 --- /dev/null +++ b/components/lib/AdvancedSearch/constants.d.ts @@ -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'; +}; diff --git a/components/lib/AdvancedSearch/hooks/useAdvancedSearch/index.d.ts b/components/lib/AdvancedSearch/hooks/useAdvancedSearch/index.d.ts index 07a2474..d1c0305 100644 --- a/components/lib/AdvancedSearch/hooks/useAdvancedSearch/index.d.ts +++ b/components/lib/AdvancedSearch/hooks/useAdvancedSearch/index.d.ts @@ -1,2 +1 @@ -declare const useAdvancedSearch: any; -export default useAdvancedSearch; +export { default } from './useAdvancedSearch'; diff --git a/components/lib/AdvancedSearch/hooks/useAdvancedSearch/useAdvancedSearch.d.ts b/components/lib/AdvancedSearch/hooks/useAdvancedSearch/useAdvancedSearch.d.ts new file mode 100644 index 0000000..c5d704a --- /dev/null +++ b/components/lib/AdvancedSearch/hooks/useAdvancedSearch/useAdvancedSearch.d.ts @@ -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 `` */ + 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; +}; diff --git a/components/lib/AdvancedSearch/index.d.ts b/components/lib/AdvancedSearch/index.d.ts index a0bef5f..54a04a7 100644 --- a/components/lib/AdvancedSearch/index.d.ts +++ b/components/lib/AdvancedSearch/index.d.ts @@ -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'; diff --git a/components/lib/AdvancedSearch/utilities/defaultQueryBuilder.d.ts b/components/lib/AdvancedSearch/utilities/defaultQueryBuilder.d.ts new file mode 100644 index 0000000..8f89144 --- /dev/null +++ b/components/lib/AdvancedSearch/utilities/defaultQueryBuilder.d.ts @@ -0,0 +1,3 @@ +import { Row, RowFormatter } from '../AdvancedSearch'; + +export default function defaultQueryBuilder(rows: Row[], rowFormatter: RowFormatter[]): string;