@backstage/plugin-search-react 1.0.2-next.1 → 1.1.0

package/dist/index.d.ts

@@ -1,10 +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 React, { ReactElement, ReactNode, PropsWithChildren } from 'react';
-import { InputBaseProps } from '@material-ui/core';
-import { JsonObject } from '@backstage/types';
+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, ListProps, TypographyProps } from '@material-ui/core';
+import { AutocompleteProps } from '@material-ui/lab';
 import { AsyncState } from 'react-use/lib/useAsync';
+import { JsonValue, JsonObject } from '@backstage/types';
+import { LinkProps } from '@backstage/core-components';
 
 /**
  * @public
@@ -42,6 +44,82 @@ declare type HighlightedSearchResultTextProps = {
  */
 declare const HighlightedSearchResultText: ({ text, preTag, postTag, }: HighlightedSearchResultTextProps) => JSX.Element;
 
+/**
+ * Props for {@link SearchBarBase}.
+ *
+ * @public
+ */
+declare type SearchBarBaseProps = Omit<InputBaseProps, 'onChange'> & {
+    debounceTime?: number;
+    clearButton?: boolean;
+    onClear?: () => void;
+    onSubmit?: () => void;
+    onChange: (value: string) => void;
+};
+/**
+ * All search boxes exported by the search plugin are based on the <SearchBarBase />,
+ * and this one is based on the <InputBase /> component from Material UI.
+ * Recommended if you don't use Search Provider or Search Context.
+ *
+ * @public
+ */
+declare const SearchBarBase: ForwardRefExoticComponent<SearchBarBaseProps>;
+/**
+ * Props for {@link SearchBar}.
+ *
+ * @public
+ */
+declare type SearchBarProps = Partial<SearchBarBaseProps>;
+/**
+ * Recommended search bar when you use the Search Provider or Search Context.
+ *
+ * @public
+ */
+declare const SearchBar: ForwardRefExoticComponent<SearchBarProps>;
+
+/**
+ * Props for {@link SearchAutocomplete}.
+ *
+ * @public
+ */
+declare type SearchAutocompleteProps<Option> = Omit<AutocompleteProps<Option, undefined, undefined, boolean>, 'renderInput' | 'disableClearable' | 'multiple'> & {
+    'data-testid'?: string;
+    inputPlaceholder?: SearchBarProps['placeholder'];
+    inputDebounceTime?: SearchBarProps['debounceTime'];
+};
+/**
+ * Type for {@link SearchAutocomplete}.
+ *
+ * @public
+ */
+declare type SearchAutocompleteComponent = <Option>(props: SearchAutocompleteProps<Option>) => JSX.Element;
+/**
+ * Recommended search autocomplete when you use the Search Provider or Search Context.
+ *
+ * @public
+ */
+declare const SearchAutocomplete: SearchAutocompleteComponent;
+
+/**
+ * Props for {@link SearchAutocompleteDefaultOption}.
+ *
+ * @public
+ */
+declare type SearchAutocompleteDefaultOptionProps = {
+    icon?: ReactNode;
+    primaryText: ListItemTextProps['primary'];
+    primaryTextTypographyProps?: ListItemTextProps['primaryTypographyProps'];
+    secondaryText?: ListItemTextProps['secondary'];
+    secondaryTextTypographyProps?: ListItemTextProps['secondaryTypographyProps'];
+    disableTextTypography?: ListItemTextProps['disableTypography'];
+};
+/**
+ * A default search autocomplete option component.
+ *
+ * @public
+ */
+declare const SearchAutocompleteDefaultOption: ({ icon, primaryText, primaryTextTypographyProps, secondaryText, secondaryTextTypographyProps, disableTextTypography, }: SearchAutocompleteDefaultOptionProps) => JSX.Element;
+
 /**
  * @public
  */
@@ -109,25 +187,128 @@ 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 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 SearchResultComponent: ({ children }: 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 HigherOrderSearchResult: (props: SearchResultProps) => JSX.Element;
+declare const SearchResult: (props: SearchResultProps) => JSX.Element;
 
 /**
  * @public
@@ -135,37 +316,200 @@ declare const HigherOrderSearchResult: (props: SearchResultProps) => JSX.Element
 declare const SearchResultPager: () => JSX.Element;
 
 /**
- * Props for {@link SearchBarBase}.
- *
+ * Props for {@link SearchResultListLayout}
  * @public
  */
-declare type SearchBarBaseProps = Omit<InputBaseProps, 'onChange'> & {
-    debounceTime?: number;
-    clearButton?: boolean;
-    onClear?: () => void;
-    onSubmit?: () => void;
-    onChange: (value: string) => void;
+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;
 };
 /**
- * All search boxes exported by the search plugin are based on the <SearchBarBase />,
- * and this one is based on the <InputBase /> component from Material UI.
- * Recommended if you don't use Search Provider or Search Context.
- *
+ * Default layout for rendering search results in a list.
+ * @param props - See {@link SearchResultListLayoutProps}.
  * @public
  */
-declare const SearchBarBase: ({ onChange, onKeyDown, onSubmit, debounceTime, clearButton, fullWidth, value: defaultValue, inputProps: defaultInputProps, endAdornment: defaultEndAdornment, ...props }: SearchBarBaseProps) => JSX.Element;
+declare const SearchResultListLayout: (props: SearchResultListLayoutProps) => JSX.Element;
 /**
- * Props for {@link SearchBar}.
- *
+ * Props for {@link SearchResultList}.
  * @public
  */
-declare type SearchBarProps = Partial<SearchBarBaseProps>;
+declare type SearchResultListProps = Omit<SearchResultListLayoutProps, 'loading' | 'error' | 'resultItems'> & {
+    /**
+     * A search query used for requesting the results to be listed.
+     */
+    query: Partial<SearchQuery>;
+};
 /**
- * Recommended search bar when you use the Search Provider or Search Context.
- *
+ * 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 const SearchBar: ({ onChange, ...props }: SearchBarProps) => JSX.Element;
+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}
@@ -226,13 +570,29 @@ declare const useSearchContextCheck: () => boolean;
  * @public
  */
 declare type SearchContextProviderProps = PropsWithChildren<{
+    /**
+     * State initialized by a local context.
+     */
     initialState?: SearchContextState;
+    /**
+     * Do not create an inheritance from the parent, as a new initial state must be defined in a local context.
+     */
+    inheritParentContextIfAvailable?: never;
+}> | PropsWithChildren<{
+    /**
+     * Does not accept initial state since it is already initialized by parent context.
+     */
+    initialState?: never;
+    /**
+     * If true, don't create a child context if there is a parent one already defined.
+     * @remarks Defaults to false.
+     */
+    inheritParentContextIfAvailable?: boolean;
 }>;
 /**
  * @public
- *
  * Search context provider which gives you access to shared state between search components
  */
 declare const SearchContextProvider: (props: SearchContextProviderProps) => JSX.Element;
 
-export { AutocompleteFilter, CheckboxFilter, HigherOrderDefaultResultListItem as DefaultResultListItem, DefaultResultListItemProps, HighlightedSearchResultText, HighlightedSearchResultTextProps, MockSearchApi, SearchApi, SearchAutocompleteFilterProps, 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 };