From 4aca2a5307ada0105be43c4e587caf701e25ddda Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Thu, 30 Dec 2021 15:12:47 +0100 Subject: [PATCH] Update search plugin API report and add changesets. Signed-off-by: Eric Peterson --- .changeset/search-something-new.md | 76 ++++++++++++++++++++++++++++++ .changeset/search-under-the-sun.md | 9 ++++ plugins/search/api-report.md | 51 ++++++++++++++++---- 3 files changed, 128 insertions(+), 8 deletions(-) create mode 100644 .changeset/search-something-new.md create mode 100644 .changeset/search-under-the-sun.md diff --git a/.changeset/search-something-new.md b/.changeset/search-something-new.md new file mode 100644 index 0000000000..260d1055a4 --- /dev/null +++ b/.changeset/search-something-new.md @@ -0,0 +1,76 @@ +--- +'@backstage/create-app': patch +--- + +An example instance of the new `` was added to the composed `SearchPage.tsx`, allowing searches bound to the `techdocs` type to be filtered by entity name. + +This is an entirely optional change; if you wish to adopt it, you can make the following (or similar) changes to your search page layout: + +```diff +--- a/packages/app/src/components/search/SearchPage.tsx ++++ b/packages/app/src/components/search/SearchPage.tsx +@@ -2,6 +2,10 @@ import React from 'react'; + import { makeStyles, Theme, Grid, List, Paper } from '@material-ui/core'; + + import { CatalogResultListItem } from '@backstage/plugin-catalog'; ++import { ++ catalogApiRef, ++ CATALOG_FILTER_EXISTS, ++} from '@backstage/plugin-catalog-react'; + import { DocsResultListItem } from '@backstage/plugin-techdocs'; + + import { +@@ -10,6 +14,7 @@ import { + SearchResult, + SearchType, + DefaultResultListItem, ++ useSearch, + } from '@backstage/plugin-search'; + import { + CatalogIcon, +@@ -18,6 +23,7 @@ import { + Header, + Page, + } from '@backstage/core-components'; ++import { useApi } from '@backstage/core-plugin-api'; + + const useStyles = makeStyles((theme: Theme) => ({ + bar: { +@@ -36,6 +42,8 @@ const useStyles = makeStyles((theme: Theme) => ({ + + const SearchPage = () => { + const classes = useStyles(); ++ const { types } = useSearch(); ++ const catalogApi = useApi(catalogApiRef); + + return ( + +@@ -65,6 +73,27 @@ const SearchPage = () => { + ]} + /> + ++ {types.includes('techdocs') && ( ++ { ++ // Return a list of entitis which are documented. ++ const { items } = await catalogApi.getEntities({ ++ fields: ['metadata.name'], ++ filter: { ++ 'metadata.annotations.backstage.io/techdocs-ref': ++ CATALOG_FILTER_EXISTS, ++ }, ++ }); ++ ++ return items ++ .map(entity => entity.metadata.name) ++ .filter(name => name.includes(partial)); ++ }} ++ /> ++ )} + ` variant, which can be used as either a single- or multi-select autocomplete. + +This variant, as well as ``, now also supports loading allowed values asynchronously with a new `asyncValues` prop, which takes an asynchronous function that resolves to the list of values (an optional `asyncDebounce` prop may also be provided). + +Check the [search plugin storybook](https://backstage.io/storybook/?path=/story/plugins-search-searchfilter) to see how to leverage these new additions. diff --git a/plugins/search/api-report.md b/plugins/search/api-report.md index 0a7da01ffd..b63271b94d 100644 --- a/plugins/search/api-report.md +++ b/plugins/search/api-report.md @@ -92,6 +92,12 @@ export interface SearchApi { // @public (undocumented) export const searchApiRef: ApiRef; +// @public (undocumented) +export type SearchAutocompleteFilterProps = SearchFilterComponentProps & { + multiple?: boolean; + limitTags?: number; +}; + // @public export const SearchBar: ({ onChange, ...props }: SearchBarProps) => JSX.Element; @@ -143,18 +149,49 @@ export const SearchContextProvider: ({ // // @public (undocumented) export const SearchFilter: { - ({ component: Element, ...props }: Props): JSX.Element; - Checkbox(props: Omit & Component): JSX.Element; - Select(props: Omit & Component): JSX.Element; + ({ component: Element, ...props }: SearchFilterWrapperProps): JSX.Element; + Checkbox( + props: Omit & + SearchFilterComponentProps, + ): JSX.Element; + Select( + props: Omit & + SearchFilterComponentProps, + ): JSX.Element; + Autocomplete(props: SearchAutocompleteFilterProps): JSX.Element; +}; + +// @public (undocumented) +export type SearchFilterComponentProps = { + className?: string; + name: string; + label?: string; + values?: string[]; + asyncValues?: (partial: string) => Promise; + asyncDebounce?: number; + defaultValue?: string[] | string | null; }; // Warning: (ae-missing-release-tag) "SearchFilterNext" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @deprecated (undocumented) export const SearchFilterNext: { - ({ component: Element, ...props }: Props): JSX.Element; - Checkbox(props: Omit & Component): JSX.Element; - Select(props: Omit & Component): JSX.Element; + ({ component: Element, ...props }: SearchFilterWrapperProps): JSX.Element; + Checkbox( + props: Omit & + SearchFilterComponentProps, + ): JSX.Element; + Select( + props: Omit & + SearchFilterComponentProps, + ): JSX.Element; + Autocomplete(props: SearchAutocompleteFilterProps): JSX.Element; +}; + +// @public (undocumented) +export type SearchFilterWrapperProps = SearchFilterComponentProps & { + component: (props: SearchFilterComponentProps) => ReactElement; + debug?: boolean; }; // Warning: (ae-missing-release-tag) "SearchModal" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -284,6 +321,4 @@ export const useSearch: () => SearchContextValue; // Warnings were encountered during analysis: // // src/components/SearchContext/SearchContext.d.ts:23:5 - (ae-forgotten-export) The symbol "SettableSearchContext" needs to be exported by the entry point index.d.ts -// src/components/SearchFilter/SearchFilter.d.ts:13:5 - (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// src/components/SearchFilter/SearchFilter.d.ts:14:5 - (ae-forgotten-export) The symbol "Component" needs to be exported by the entry point index.d.ts ```