@backstage/plugin-search-react 1.4.0-next.2 → 1.5.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @backstage/plugin-search-react
 
+## 1.5.0-next.0
+
+### Minor Changes
+
+- 0eaa579f89: - Create the search results extensions, for more details see the documentation [here](https://backstage.io/docs/features/search/how-to-guides#how-to-render-search-results-using-extensions);
+  - Update the `SearchResult`, `SearchResultList` and `SearchResultGroup` components to use extensions and default their props to optionally accept a query, when the query is not passed, the component tries to get it from the search context.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-components@0.12.4-next.0
+  - @backstage/core-plugin-api@1.3.0
+  - @backstage/theme@0.2.16
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+  - @backstage/plugin-search-common@1.2.1
+
+## 1.4.0
+
+### Minor Changes
+
+- 6d9a93def8: Allow customizing empty state component through `noResultsComponent` property.
+
+  Example:
+
+  ```jsx
+  <SearchResult noResultsComponent={<>No results were found</>}>
+    {({ results }) => (
+      <List>
+        {results.map(({ type, document }) => {
+          switch (type) {
+            case 'custom-result-item':
+              return (
+                <CustomResultListItem
+                  key={document.location}
+                  result={document}
+                />
+              );
+            default:
+              return (
+                <DefaultResultListItem
+                  key={document.location}
+                  result={document}
+                />
+              );
+          }
+        })}
+      </List>
+    )}
+  </SearchResult>
+  ```
+
+### Patch Changes
+
+- 80ce4e8c29: Small updates to some components to ensure theme typography properties are inherited correctly.
+- Updated dependencies
+  - @backstage/core-components@0.12.3
+  - @backstage/core-plugin-api@1.3.0
+  - @backstage/theme@0.2.16
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+  - @backstage/plugin-search-common@1.2.1
+
 ## 1.4.0-next.2
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="react" />
 import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
+import { Extension } from '@backstage/core-plugin-api';
 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 React, { ReactNode, ForwardRefExoticComponent, ReactElement, PropsWithChildren } from 'react';
+import { ListProps, InputBaseProps, ListItemTextProps, TypographyProps } from '@material-ui/core';
 import { AutocompleteProps } from '@material-ui/lab';
 import { AsyncState } from 'react-use/lib/useAsync';
 import { JsonValue, JsonObject } from '@backstage/types';
@@ -29,6 +30,53 @@ declare class MockSearchApi implements SearchApi {
     query(): Promise<SearchResultSet>;
 }
 
+/**
+ * @public
+ * Options for {@link createSearchResultListItemExtension}.
+ */
+declare type SearchResultListItemExtensionOptions<Component extends (props: any) => JSX.Element | null> = {
+    /**
+     * The extension name.
+     */
+    name: string;
+    /**
+     * The extension component.
+     */
+    component: () => Promise<Component>;
+    /**
+     * When an extension defines a predicate, it returns true if the result should be rendered by that extension.
+     * Defaults to a predicate that returns true, which means it renders all sorts of results.
+     */
+    predicate?: (result: SearchResult$1) => boolean;
+};
+/**
+ * @public
+ * Creates a search result item extension.
+ * @param options - The extension options, see {@link SearchResultListItemExtensionOptions} for more details.
+ */
+declare const createSearchResultListItemExtension: <Component extends (props: any) => JSX.Element | null>(options: SearchResultListItemExtensionOptions<Component>) => Extension<Component>;
+/**
+ * @public
+ * Returns a function that renders a result using extensions.
+ */
+declare const useSearchResultListItemExtensions: (children: ReactNode) => (result: SearchResult$1, key?: number) => JSX.Element;
+/**
+ * @public
+ * Props for {@link SearchResultListItemExtensions}
+ */
+declare type SearchResultListItemExtensionsProps = Omit<ListProps, 'results'> & {
+    /**
+     * Search result list.
+     */
+    results: SearchResult$1[];
+};
+/**
+ * @public
+ * Render results using search extensions.
+ * @param props - see {@link SearchResultListItemExtensionsProps}
+ */
+declare const SearchResultListItemExtensions: (props: SearchResultListItemExtensionsProps) => JSX.Element;
+
 /**
  * Props for {@link HighlightedSearchResultText}.
  *
@@ -186,6 +234,92 @@ declare const SearchFilter: {
     Autocomplete(props: SearchAutocompleteFilterProps): JSX.Element;
 };
 
+/**
+ * A page limit option, this value must not be greater than 100.
+ * @public
+ */
+declare type SearchPaginationLimitOption<Current extends number = 101, Accumulator extends number[] = []> = Accumulator['length'] extends Current ? Accumulator[number] : SearchPaginationLimitOption<Current, [
+    ...Accumulator,
+    Accumulator['length']
+]>;
+/**
+ * A page limit text, this function is called with a "\{ from, to, page, count \}" object.
+ * @public
+ */
+declare type SearchPaginationLimitText = (params: {
+    from: number;
+    to: number;
+    page: number;
+    count: number;
+}) => ReactNode;
+/**
+ * Props for {@link SearchPaginationBase}.
+ * @public
+ */
+declare type SearchPaginationBaseProps = {
+    /**
+     * The component class name.
+     */
+    className?: string;
+    /**
+     * The total number of results.
+     * For an unknown number of items, provide -1.
+     * Defaults to -1.
+     */
+    total?: number;
+    /**
+     * The cursor for the current page.
+     */
+    cursor?: string;
+    /**
+     * Callback fired when the current page cursor is changed.
+     */
+    onCursorChange?: (pageCursor: string) => void;
+    /**
+     * The limit of results per page.
+     * Set -1 to display all the results.
+     */
+    limit?: number;
+    /**
+     * Customize the results per page label.
+     * Defaults to "Results per page:".
+     */
+    limitLabel?: ReactNode;
+    /**
+     * Customize the results per page text.
+     * Defaults to "(\{ from, to, count \}) =\> count \> 0 ? `of $\{count\}` : `$\{from\}-$\{to\}`".
+     */
+    limitText?: SearchPaginationLimitText;
+    /**
+     * Options for setting how many results show per page.
+     * If less than two options are available, no select field will be displayed.
+     * Use -1 for the value with a custom label to show all the results.
+     * Defaults to [10, 25, 50, 100].
+     */
+    limitOptions?: SearchPaginationLimitOption[];
+    /**
+     * Callback fired when the number of results per page is changed.
+     */
+    onLimitChange?: (value: number) => void;
+};
+/**
+ * A component with controls for search results pagination.
+ * @param props - See {@link SearchPaginationBaseProps}.
+ * @public
+ */
+declare const SearchPaginationBase: (props: SearchPaginationBaseProps) => JSX.Element;
+/**
+ * Props for {@link SearchPagination}.
+ * @public
+ */
+declare type SearchPaginationProps = Omit<SearchPaginationBaseProps, 'pageLimit' | 'onPageLimitChange' | 'pageCursor' | 'onPageCursorChange'>;
+/**
+ * A component for setting the search context page limit and cursor.
+ * @param props - See {@link SearchPaginationProps}.
+ * @public
+ */
+declare const SearchPagination: (props: SearchPaginationProps) => JSX.Element;
+
 /**
  * Props for {@link SearchResultContext}
  * @public
@@ -194,7 +328,7 @@ declare type SearchResultContextProps = {
     /**
      * A child function that receives an asynchronous result set and returns a react element.
      */
-    children: (state: AsyncState<SearchResultSet>) => JSX.Element | null;
+    children: (state: AsyncState<SearchResultSet>, query: Partial<SearchQuery>) => JSX.Element | null;
 };
 /**
  * Provides context-based results to a child function.
@@ -293,8 +427,8 @@ declare const SearchResultState: (props: SearchResultStateProps) => JSX.Element;
  * Props for {@link SearchResult}
  * @public
  */
-declare type SearchResultProps = Pick<SearchResultStateProps, 'query'> & {
-    children: (resultSet: SearchResultSet) => JSX.Element;
+declare type SearchResultProps = Pick<SearchResultStateProps, 'query'> & Omit<SearchResultListItemExtensionsProps, 'results' | 'children'> & {
+    children?: ReactNode | ((resultSet: SearchResultSet) => JSX.Element);
     noResultsComponent?: JSX.Element;
 };
 /**
@@ -312,101 +446,18 @@ declare const SearchResultComponent: (props: SearchResultProps) => JSX.Element;
 declare const SearchResult: (props: SearchResultProps) => JSX.Element;
 
 /**
+ * Props for {@link SearchResultListLayout}
  * @public
  */
-declare const SearchResultPager: () => JSX.Element;
-
-/**
- * A page limit option, this value must not be greater than 100.
- * @public
- */
-declare type SearchPaginationLimitOption<Current extends number = 101, Accumulator extends number[] = []> = Accumulator['length'] extends Current ? Accumulator[number] : SearchPaginationLimitOption<Current, [
-    ...Accumulator,
-    Accumulator['length']
-]>;
-/**
- * A page limit text, this function is called with a "\{ from, to, page, count \}" object.
- * @public
- */
-declare type SearchPaginationLimitText = (params: {
-    from: number;
-    to: number;
-    page: number;
-    count: number;
-}) => ReactNode;
-/**
- * Props for {@link SearchPaginationBase}.
- * @public
- */
-declare type SearchPaginationBaseProps = {
-    /**
-     * The component class name.
-     */
-    className?: string;
-    /**
-     * The total number of results.
-     * For an unknown number of items, provide -1.
-     * Defaults to -1.
-     */
-    total?: number;
-    /**
-     * The cursor for the current page.
-     */
-    cursor?: string;
-    /**
-     * Callback fired when the current page cursor is changed.
-     */
-    onCursorChange?: (pageCursor: string) => void;
-    /**
-     * The limit of results per page.
-     * Set -1 to display all the results.
-     */
-    limit?: number;
-    /**
-     * Customize the results per page label.
-     * Defaults to "Results per page:".
-     */
-    limitLabel?: ReactNode;
-    /**
-     * Customize the results per page text.
-     * Defaults to "(\{ from, to, count \}) =\> count \> 0 ? `of $\{count\}` : `$\{from\}-$\{to\}`".
-     */
-    limitText?: SearchPaginationLimitText;
+declare type SearchResultListLayoutProps = ListProps & {
     /**
-     * Options for setting how many results show per page.
-     * If less than two options are available, no select field will be displayed.
-     * Use -1 for the value with a custom label to show all the results.
-     * Defaults to [10, 25, 50, 100].
+     * If defined, will render a default error panel.
      */
-    limitOptions?: SearchPaginationLimitOption[];
+    error?: Error;
     /**
-     * Callback fired when the number of results per page is changed.
+     * If defined, will render a default loading progress.
      */
-    onLimitChange?: (value: number) => void;
-};
-/**
- * A component with controls for search results pagination.
- * @param props - See {@link SearchPaginationBaseProps}.
- * @public
- */
-declare const SearchPaginationBase: (props: SearchPaginationBaseProps) => JSX.Element;
-/**
- * Props for {@link SearchPagination}.
- * @public
- */
-declare type SearchPaginationProps = Omit<SearchPaginationBaseProps, 'pageLimit' | 'onPageLimitChange' | 'pageCursor' | 'onPageCursorChange'>;
-/**
- * A component for setting the search context page limit and cursor.
- * @param props - See {@link SearchPaginationProps}.
- * @public
- */
-declare const SearchPagination: (props: SearchPaginationProps) => JSX.Element;
-
-/**
- * Props for {@link SearchResultListLayout}
- * @public
- */
-declare type SearchResultListLayoutProps = ListProps & {
+    loading?: boolean;
     /**
      * Search results to be rendered as a list.
      */
@@ -415,18 +466,14 @@ declare type SearchResultListLayoutProps = ListProps & {
      * Function to customize how result items are rendered.
      */
     renderResultItem?: (value: SearchResult$1, index: number, array: SearchResult$1[]) => JSX.Element | null;
-    /**
-     * If defined, will render a default error panel.
-     */
-    error?: Error;
-    /**
-     * If defined, will render a default loading progress.
-     */
-    loading?: boolean;
     /**
      * Optional component to render when no results. Default to <EmptyState /> component.
      */
     noResultsComponent?: ReactNode;
+    /**
+     * Optional property to provide if component should not render the component when no results are found.
+     */
+    disableRenderingWithNoResults?: boolean;
 };
 /**
  * Default layout for rendering search results in a list.
@@ -438,16 +485,7 @@ declare const SearchResultListLayout: (props: SearchResultListLayoutProps) => JS
  * 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>;
-    /**
-     * Optional property to provide if component should not render the component when no results are found.
-     */
-    disableRenderingWithNoResults?: boolean;
-};
+declare type SearchResultListProps = Pick<SearchResultStateProps, 'query'> & Omit<SearchResultListLayoutProps, 'loading' | 'error' | 'resultItems'>;
 /**
  * Given a query, search for results and render them as a list.
  * @param props - See {@link SearchResultListProps}.
@@ -529,6 +567,14 @@ declare const SearchResultGroupSelectFilterField: (props: SearchResultGroupSelec
  * @public
  */
 declare type SearchResultGroupLayoutProps<FilterOption> = ListProps & {
+    /**
+     * If defined, will render a default error panel.
+     */
+    error?: Error;
+    /**
+     * If defined, will render a default loading progress.
+     */
+    loading?: boolean;
     /**
      * Icon that representing a result group.
      */
@@ -574,18 +620,14 @@ declare type SearchResultGroupLayoutProps<FilterOption> = ListProps & {
      * Function to customize how result items are rendered.
      */
     renderResultItem?: (value: SearchResult$1, index: number, array: SearchResult$1[]) => JSX.Element | null;
-    /**
-     * If defined, will render a default error panel.
-     */
-    error?: Error;
-    /**
-     * If defined, will render a default loading progress.
-     */
-    loading?: boolean;
     /**
      * Optional component to render when no results. Default to <EmptyState /> component.
      */
     noResultsComponent?: ReactNode;
+    /**
+     * Optional property to provide if component should not render the component when no results are found.
+     */
+    disableRenderingWithNoResults?: boolean;
 };
 /**
  * Default layout for rendering search results in a group.
@@ -597,16 +639,7 @@ declare function SearchResultGroupLayout<FilterOption>(props: SearchResultGroupL
  * 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>;
-    /**
-     * Optional property to provide if component should not render the group when no results are found.
-     */
-    disableRenderingWithNoResults?: boolean;
-};
+declare type SearchResultGroupProps<FilterOption> = Pick<SearchResultStateProps, 'query'> & Omit<SearchResultGroupLayoutProps<FilterOption>, 'loading' | 'error' | 'resultItems' | 'filterFields'>;
 /**
  * Given a query, search for results and render them as a group.
  * @param props - See {@link SearchResultGroupProps}.
@@ -614,6 +647,11 @@ declare type SearchResultGroupProps<FilterOption> = Omit<SearchResultGroupLayout
  */
 declare function SearchResultGroup<FilterOption>(props: SearchResultGroupProps<FilterOption>): JSX.Element;
 
+/**
+ * @public
+ */
+declare const SearchResultPager: () => JSX.Element;
+
 /**
  * Props for {@link DefaultResultListItem}
  *
@@ -622,7 +660,7 @@ declare function SearchResultGroup<FilterOption>(props: SearchResultGroupProps<F
 declare type DefaultResultListItemProps = {
     icon?: ReactNode;
     secondaryAction?: ReactNode;
-    result: SearchDocument;
+    result?: SearchDocument;
     highlight?: ResultHighlight;
     rank?: number;
     lineClamp?: number;
@@ -700,4 +738,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, SearchPagination, SearchPaginationBase, SearchPaginationBaseProps, SearchPaginationLimitOption, SearchPaginationLimitText, SearchPaginationProps, 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 };
+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, SearchPagination, SearchPaginationBase, SearchPaginationBaseProps, SearchPaginationLimitOption, SearchPaginationLimitText, SearchPaginationProps, SearchResult, SearchResultApi, SearchResultApiProps, SearchResultComponent, SearchResultContext, SearchResultContextProps, SearchResultGroup, SearchResultGroupFilterFieldLayout, SearchResultGroupFilterFieldLayoutProps, SearchResultGroupFilterFieldPropsWith, SearchResultGroupLayout, SearchResultGroupLayoutProps, SearchResultGroupProps, SearchResultGroupSelectFilterField, SearchResultGroupSelectFilterFieldProps, SearchResultGroupTextFilterField, SearchResultGroupTextFilterFieldProps, SearchResultList, SearchResultListItemExtensionOptions, SearchResultListItemExtensions, SearchResultListItemExtensionsProps, SearchResultListLayout, SearchResultListLayoutProps, SearchResultListProps, SearchResultPager, SearchResultProps, SearchResultState, SearchResultStateProps, SelectFilter, createSearchResultListItemExtension, searchApiRef, useSearch, useSearchContextCheck, useSearchResultListItemExtensions };