@backstage/plugin-search-react 1.1.0-next.2 → 1.1.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 /// <reference types="react" />
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
-import { SearchQuery, SearchResultSet, SearchResult, SearchDocument, ResultHighlight } from '@backstage/plugin-search-common';
+import { SearchQuery, SearchResultSet, SearchResult as SearchResult$1, SearchDocument, ResultHighlight } from '@backstage/plugin-search-common';
 import React, { ForwardRefExoticComponent, ReactNode, ReactElement, PropsWithChildren } from 'react';
-import { InputBaseProps, ListItemTextProps } from '@material-ui/core';
+import { InputBaseProps, ListItemTextProps, ListProps, TypographyProps } from '@material-ui/core';
 import { AutocompleteProps } from '@material-ui/lab';
-import { JsonObject } from '@backstage/types';
 import { AsyncState } from 'react-use/lib/useAsync';
+import { JsonValue, JsonObject } from '@backstage/types';
+import { LinkProps } from '@backstage/core-components';
 
 /**
  * @public
@@ -186,31 +187,330 @@ declare const SearchFilter: {
 };
 
 /**
- * Props for {@link SearchResultComponent}
- *
+ * Props for {@link SearchResultContext}
  * @public
  */
-declare type SearchResultProps = {
-    children: (results: {
-        results: SearchResult[];
-    }) => JSX.Element;
+declare type SearchResultContextProps = {
+    /**
+     * A child function that receives an asynchronous result set and returns a react element.
+     */
+    children: (state: AsyncState<SearchResultSet>) => JSX.Element;
 };
 /**
- * A component returning the search result.
- *
+ * Provides context-based results to a child function.
+ * @param props - see {@link SearchResultContextProps}.
+ * @example
+ * ```
+ * <SearchResultContext>
+ *   {({ loading, error, value }) => (
+ *     <List>
+ *       {value?.map(({ document }) => (
+ *         <DefaultSearchResultListItem
+ *           key={document.location}
+ *           result={document}
+ *         />
+ *       ))}
+ *     </List>
+ *   )}
+ * </SearchResultContext>
+ * ```
+ * @public
+ */
+declare const SearchResultContext: (props: SearchResultContextProps) => JSX.Element;
+/**
+ * Props for {@link SearchResultApi}
  * @public
  */
-declare const SearchResultComponent: ({ children }: SearchResultProps) => JSX.Element;
+declare type SearchResultApiProps = SearchResultContextProps & {
+    query: Partial<SearchQuery>;
+};
+/**
+ * Request results through the search api and provide them to a child function.
+ * @param props - see {@link SearchResultApiProps}.
+ * @example
+ * ```
+ * <SearchResultApi>
+ *   {({ loading, error, value }) => (
+ *     <List>
+ *       {value?.map(({ document }) => (
+ *         <DefaultSearchResultListItem
+ *           key={document.location}
+ *           result={document}
+ *         />
+ *       ))}
+ *     </List>
+ *   )}
+ * </SearchResultApi>
+ * ```
+ * @public
+ */
+declare const SearchResultApi: (props: SearchResultApiProps) => JSX.Element;
+/**
+ * Props for {@link SearchResultState}
+ * @public
+ */
+declare type SearchResultStateProps = SearchResultContextProps & Partial<SearchResultApiProps>;
+/**
+ * Call a child render function passing a search state as an argument.
+ * @remarks By default, results are taken from context, but when a "query" prop is set, results are requested from the search api.
+ * @param props - see {@link SearchResultStateProps}.
+ * @example
+ * Consuming results from context:
+ * ```
+ * <SearchResultState>
+ *   {({ loading, error, value }) => (
+ *     <List>
+ *       {value?.map(({ document }) => (
+ *         <DefaultSearchResultListItem
+ *           key={document.location}
+ *           result={document}
+ *         />
+ *       ))}
+ *     </List>
+ *   )}
+ * </SearchResultState>
+ * ```
+ * @example
+ * Requesting results using the search api:
+ * ```
+ * <SearchResultState query={{ term: 'documentation' }}>
+ *   {({ loading, error, value }) => (
+ *     <List>
+ *       {value?.map(({ document }) => (
+ *         <DefaultSearchResultListItem
+ *           key={document.location}
+ *           result={document}
+ *         />
+ *       ))}
+ *     </List>
+ *   )}
+ * </SearchResultState>
+ * ```
+ * @public
+ */
+declare const SearchResultState: (props: SearchResultStateProps) => JSX.Element;
+/**
+ * Props for {@link SearchResult}
+ * @public
+ */
+declare type SearchResultProps = Pick<SearchResultStateProps, 'query'> & {
+    children: (resultSet: SearchResultSet) => JSX.Element;
+};
 /**
+ * Renders results from a parent search context or api.
+ * @remarks default components for loading, error and empty variants are returned.
+ * @param props - see {@link SearchResultProps}.
  * @public
  */
-declare const HigherOrderSearchResult: (props: SearchResultProps) => JSX.Element;
+declare const SearchResultComponent: (props: SearchResultProps) => JSX.Element;
+/**
+ * A component returning the search result from a parent search context or api.
+ * @param props - see {@link SearchResultProps}.
+ * @public
+ */
+declare const SearchResult: (props: SearchResultProps) => JSX.Element;
 
 /**
  * @public
  */
 declare const SearchResultPager: () => JSX.Element;
 
+/**
+ * Props for {@link SearchResultListLayout}
+ * @public
+ */
+declare type SearchResultListLayoutProps = ListProps & {
+    /**
+     * Search results to be rendered as a list.
+     */
+    resultItems?: SearchResult$1[];
+    /**
+     * Function to customize how result items are rendered.
+     */
+    renderResultItem?: (resultItem: SearchResult$1) => JSX.Element;
+    /**
+     * If defined, will render a default error panel.
+     */
+    error?: Error;
+    /**
+     * If defined, will render a default loading progress.
+     */
+    loading?: boolean;
+};
+/**
+ * Default layout for rendering search results in a list.
+ * @param props - See {@link SearchResultListLayoutProps}.
+ * @public
+ */
+declare const SearchResultListLayout: (props: SearchResultListLayoutProps) => JSX.Element;
+/**
+ * Props for {@link SearchResultList}.
+ * @public
+ */
+declare type SearchResultListProps = Omit<SearchResultListLayoutProps, 'loading' | 'error' | 'resultItems'> & {
+    /**
+     * A search query used for requesting the results to be listed.
+     */
+    query: Partial<SearchQuery>;
+};
+/**
+ * Given a query, search for results and render them as a list.
+ * @param props - See {@link SearchResultListProps}.
+ * @public
+ */
+declare const SearchResultList: (props: SearchResultListProps) => JSX.Element;
+
+/**
+ * Props for {@link SearchResultGroupFilterFieldLayout}
+ * @public
+ */
+declare type SearchResultGroupFilterFieldLayoutProps = PropsWithChildren<{
+    label: string;
+    value?: JsonValue;
+    onDelete: () => void;
+}>;
+/**
+ * Default layout for a search group filter field.
+ * @param props - See {@link SearchResultGroupFilterFieldLayoutProps}.
+ * @public
+ */
+declare const SearchResultGroupFilterFieldLayout: (props: SearchResultGroupFilterFieldLayoutProps) => JSX.Element;
+/**
+ * Common props for a result group filter field.
+ * @public
+ */
+declare type SearchResultGroupFilterFieldPropsWith<T> = T & SearchResultGroupFilterFieldLayoutProps & {
+    onChange: (value: JsonValue) => void;
+};
+/**
+ * Props for {@link SearchResultGroupTextFilterField}.
+ * @public
+ */
+declare type SearchResultGroupTextFilterFieldProps = SearchResultGroupFilterFieldPropsWith<{}>;
+/**
+ * A text field that can be used as filter on search result groups.
+ * @param props - See {@link SearchResultGroupTextFilterFieldProps}.
+ * @example
+ * ```
+ * <SearchResultGroupTextFilterField
+ *   id="lifecycle"
+ *   label="Lifecycle"
+ *   value={value}
+ *   onChange={handleChangeFilter}
+ *   onDelete={handleDeleteFilter}
+ * />
+ * ```
+ * @public
+ */
+declare const SearchResultGroupTextFilterField: (props: SearchResultGroupTextFilterFieldProps) => JSX.Element;
+/**
+ * Props for {@link SearchResultGroupTextFilterField}.
+ * @public
+ */
+declare type SearchResultGroupSelectFilterFieldProps = SearchResultGroupFilterFieldPropsWith<{
+    children: ReactNode;
+}>;
+/**
+ * A select field that can be used as filter on search result groups.
+ * @param props - See {@link SearchResultGroupSelectFilterFieldProps}.
+ * @example
+ * ```
+ * <SearchResultGroupSelectFilterField
+ *   id="lifecycle"
+ *   label="Lifecycle"
+ *   value={filters.lifecycle}
+ *   onChange={handleChangeFilter}
+ *   onDelete={handleDeleteFilter}
+ * >
+ *   <MenuItem value="experimental">Experimental</MenuItem>
+ *   <MenuItem value="production">Production</MenuItem>
+ *  </SearchResultGroupSelectFilterField>
+ * ```
+ * @public
+ */
+declare const SearchResultGroupSelectFilterField: (props: SearchResultGroupSelectFilterFieldProps) => JSX.Element;
+/**
+ * Props for {@link SearchResultGroupLayout}
+ * @public
+ */
+declare type SearchResultGroupLayoutProps<FilterOption> = ListProps & {
+    /**
+     * Icon that representing a result group.
+     */
+    icon: JSX.Element;
+    /**
+     * The results group title content, it could be a text or an element.
+     */
+    title: ReactNode;
+    /**
+     * Props for the results group title.
+     */
+    titleProps?: Partial<TypographyProps>;
+    /**
+     * The results group link content, it could be a text or an element.
+     */
+    link?: ReactNode;
+    /**
+     * Props for the results group link, the "to" prop defaults to "/search".
+     */
+    linkProps?: Partial<LinkProps>;
+    /**
+     * A generic filter options that is rendered on the "Add filter" dropdown.
+     */
+    filterOptions?: FilterOption[];
+    /**
+     * Function to customize how filter options are rendered.
+     * @remarks Defaults to a menu item where its value and label bounds to the option string.
+     */
+    renderFilterOption?: (filterOption: FilterOption) => JSX.Element;
+    /**
+     * A list of search filter keys, also known as filter field names.
+     */
+    filterFields?: string[];
+    /**
+     * Function to customize how filter chips are rendered.
+     */
+    renderFilterField?: (key: string) => JSX.Element | null;
+    /**
+     * Search results to be rendered as a group.
+     */
+    resultItems?: SearchResult$1[];
+    /**
+     * Function to customize how result items are rendered.
+     */
+    renderResultItem?: (resultItem: SearchResult$1) => JSX.Element;
+    /**
+     * If defined, will render a default error panel.
+     */
+    error?: Error;
+    /**
+     * If defined, will render a default loading progress.
+     */
+    loading?: boolean;
+};
+/**
+ * Default layout for rendering search results in a group.
+ * @param props - See {@link SearchResultGroupLayoutProps}.
+ * @public
+ */
+declare function SearchResultGroupLayout<FilterOption>(props: SearchResultGroupLayoutProps<FilterOption>): JSX.Element;
+/**
+ * Props for {@link SearchResultGroup}.
+ * @public
+ */
+declare type SearchResultGroupProps<FilterOption> = Omit<SearchResultGroupLayoutProps<FilterOption>, 'loading' | 'error' | 'resultItems' | 'filterFields'> & {
+    /**
+     * A search query used for requesting the results to be grouped.
+     */
+    query: Partial<SearchQuery>;
+};
+/**
+ * Given a query, search for results and render them as a group.
+ * @param props - See {@link SearchResultGroupProps}.
+ * @public
+ */
+declare function SearchResultGroup<FilterOption>(props: SearchResultGroupProps<FilterOption>): JSX.Element;
+
 /**
  * Props for {@link DefaultResultListItem}
  *
@@ -295,4 +595,4 @@ declare type SearchContextProviderProps = PropsWithChildren<{
  */
 declare const SearchContextProvider: (props: SearchContextProviderProps) => JSX.Element;
 
-export { AutocompleteFilter, CheckboxFilter, HigherOrderDefaultResultListItem as DefaultResultListItem, DefaultResultListItemProps, HighlightedSearchResultText, HighlightedSearchResultTextProps, MockSearchApi, SearchApi, SearchAutocomplete, SearchAutocompleteComponent, SearchAutocompleteDefaultOption, SearchAutocompleteDefaultOptionProps, SearchAutocompleteFilterProps, SearchAutocompleteProps, SearchBar, SearchBarBase, SearchBarBaseProps, SearchBarProps, SearchContextProvider, SearchContextProviderProps, SearchContextState, SearchContextValue, SearchFilter, SearchFilterComponentProps, SearchFilterWrapperProps, HigherOrderSearchResult as SearchResult, SearchResultComponent, SearchResultPager, SearchResultProps, SelectFilter, searchApiRef, useSearch, useSearchContextCheck };
+export { AutocompleteFilter, CheckboxFilter, HigherOrderDefaultResultListItem as DefaultResultListItem, DefaultResultListItemProps, HighlightedSearchResultText, HighlightedSearchResultTextProps, MockSearchApi, SearchApi, SearchAutocomplete, SearchAutocompleteComponent, SearchAutocompleteDefaultOption, SearchAutocompleteDefaultOptionProps, SearchAutocompleteFilterProps, SearchAutocompleteProps, SearchBar, SearchBarBase, SearchBarBaseProps, SearchBarProps, SearchContextProvider, SearchContextProviderProps, SearchContextState, SearchContextValue, SearchFilter, SearchFilterComponentProps, SearchFilterWrapperProps, SearchResult, SearchResultApi, SearchResultApiProps, SearchResultComponent, SearchResultContext, SearchResultContextProps, SearchResultGroup, SearchResultGroupFilterFieldLayout, SearchResultGroupFilterFieldLayoutProps, SearchResultGroupFilterFieldPropsWith, SearchResultGroupLayout, SearchResultGroupLayoutProps, SearchResultGroupProps, SearchResultGroupSelectFilterField, SearchResultGroupSelectFilterFieldProps, SearchResultGroupTextFilterField, SearchResultGroupTextFilterFieldProps, SearchResultList, SearchResultListLayout, SearchResultListLayoutProps, SearchResultListProps, SearchResultPager, SearchResultProps, SearchResultState, SearchResultStateProps, SelectFilter, searchApiRef, useSearch, useSearchContextCheck };