Add AdvancedSearch typings (#48)

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 */

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<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;

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';
+};

components/lib/AdvancedSearch/hooks/useAdvancedSearch/index.d.ts

@@ -1,2 +1 @@
-declare const useAdvancedSearch: any;
-export default useAdvancedSearch;
+export { default } from './useAdvancedSearch';

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 `<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;
+};

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';

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;