diff --git a/.changeset/fast-dolphins-think.md b/.changeset/fast-dolphins-think.md new file mode 100644 index 0000000000..0d96e00ea7 --- /dev/null +++ b/.changeset/fast-dolphins-think.md @@ -0,0 +1,10 @@ +--- +'@backstage/plugin-search-react': patch +--- + +api-report clean up - the package now exports following additional types: + +`SearchContextProviderProps` +`SearchContextValue` +`SearchContextProviderForStorybookProps` +`SearchApiProviderForStorybookProps` diff --git a/plugins/search-react/api-report.md b/plugins/search-react/api-report.md index f9b34e3f3f..112d864add 100644 --- a/plugins/search-react/api-report.md +++ b/plugins/search-react/api-report.md @@ -18,32 +18,41 @@ export interface SearchApi { query(query: SearchQuery): Promise; } -// Warning: (ae-forgotten-export) The symbol "QueryResultProps" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "SearchApiProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function SearchApiProviderForStorybook( - props: PropsWithChildren, + props: SearchApiProviderForStorybookProps, ): JSX.Element; +// @public +export type SearchApiProviderForStorybookProps = ComponentProps< + typeof SearchContextProvider +> & { + mockedResults?: SearchResultSet; +}; + // @public (undocumented) export const searchApiRef: ApiRef; -// @public (undocumented) -export const SearchContextProvider: ({ - initialState, - children, -}: React_2.PropsWithChildren<{ - initialState?: SearchContextState | undefined; -}>) => JSX.Element; +// @public +export const SearchContextProvider: ( + props: SearchContextProviderProps, +) => JSX.Element; -// Warning: (ae-missing-release-tag) "SearchContextProvider" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export const SearchContextProviderForStorybook: ( - props: ComponentProps & QueryResultProps, + props: SearchContextProviderForStorybookProps, ) => JSX.Element; +// @public +export type SearchContextProviderForStorybookProps = PropsWithChildren<{ + mockedResults?: SearchResultSet; +}>; + +// @public +export type SearchContextProviderProps = PropsWithChildren<{ + initialState?: SearchContextState; +}>; + // @public (undocumented) export type SearchContextState = { term: string; @@ -52,10 +61,17 @@ export type SearchContextState = { pageCursor?: string; }; -// Warning: (ae-forgotten-export) The symbol "SearchContextValue" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -export const useSearch: () => SearchContextValue; +export type SearchContextValue = { + result: AsyncState; + setTerm: React_2.Dispatch>; + setTypes: React_2.Dispatch>; + setFilters: React_2.Dispatch>; + setPageCursor: React_2.Dispatch>; + fetchNextPage?: React_2.DispatchWithoutAction; + fetchPreviousPage?: React_2.DispatchWithoutAction; +} & SearchContextState; -// (No @packageDocumentation comment for this package) +// @public +export const useSearch: () => SearchContextValue; ``` diff --git a/plugins/search-react/src/context/SearchContext.tsx b/plugins/search-react/src/context/SearchContext.tsx index 6f8067805c..9024fb5e9e 100644 --- a/plugins/search-react/src/context/SearchContext.tsx +++ b/plugins/search-react/src/context/SearchContext.tsx @@ -32,7 +32,11 @@ import useAsync, { AsyncState } from 'react-use/lib/useAsync'; import usePrevious from 'react-use/lib/usePrevious'; import { searchApiRef } from '../api'; -type SearchContextValue = { +/** + * + * @public + */ +export type SearchContextValue = { result: AsyncState; setTerm: React.Dispatch>; setTypes: React.Dispatch>; @@ -59,6 +63,8 @@ const SearchContext = createVersionedContext<{ /** * @public + * + * React hook which provides the search context */ export const useSearch = () => { const context = useContext(SearchContext); @@ -85,12 +91,21 @@ const searchInitialState: SearchContextState = { }; /** + * Props for {@link SearchContextProvider} + * * @public */ -export const SearchContextProvider = ({ - initialState = searchInitialState, - children, -}: PropsWithChildren<{ initialState?: SearchContextState }>) => { +export type SearchContextProviderProps = PropsWithChildren<{ + initialState?: SearchContextState; +}>; + +/** + * @public + * + * Search context provider which gives you access to shared state between search components + */ +export const SearchContextProvider = (props: SearchContextProviderProps) => { + const { initialState = searchInitialState, children } = props; const searchApi = useApi(searchApiRef); const [pageCursor, setPageCursor] = useState( initialState.pageCursor, diff --git a/plugins/search-react/src/context/SearchContextForStorybook.stories.tsx b/plugins/search-react/src/context/SearchContextForStorybook.stories.tsx index 51297c965f..603a89035f 100644 --- a/plugins/search-react/src/context/SearchContextForStorybook.stories.tsx +++ b/plugins/search-react/src/context/SearchContextForStorybook.stories.tsx @@ -18,35 +18,54 @@ import { SearchResultSet } from '@backstage/plugin-search-common'; import { TestApiRegistry } from '@backstage/test-utils'; import React, { ComponentProps, PropsWithChildren } from 'react'; import { searchApiRef } from '../api'; -import { SearchContextProvider as RealSearchContextProvider } from './SearchContext'; +import { SearchContextProvider } from './SearchContext'; -type QueryResultProps = { +/** + * Props for {@link SearchApiProviderForStorybook} + * @public + */ +export type SearchApiProviderForStorybookProps = ComponentProps< + typeof SearchContextProvider +> & { mockedResults?: SearchResultSet; }; +/** + * Props for {@link SearchContextProviderForStorybook} + * @public + */ +export type SearchContextProviderForStorybookProps = PropsWithChildren<{ + mockedResults?: SearchResultSet; +}>; + +/** + * Utility api provider only for use in Storybook stories. + * + * @public + */ +export function SearchApiProviderForStorybook( + props: SearchApiProviderForStorybookProps, +) { + const { mockedResults, children } = props; + const query: any = () => Promise.resolve(mockedResults || {}); + const apiRegistry = TestApiRegistry.from([searchApiRef, { query }]); + return ; +} + /** * Utility context provider only for use in Storybook stories. You should use * the real `` exported by `@backstage/plugin-search-react` in * your app instead of this! In some cases (like the search page) it may * already be provided on your behalf. + * + * @public */ -export const SearchContextProvider = ( - props: ComponentProps & QueryResultProps, +export const SearchContextProviderForStorybook = ( + props: SearchContextProviderForStorybookProps, ) => { return ( - - - + + + ); }; - -/** - * Utility api provider only for use in Storybook stories. - * - */ -export function SearchApiProvider(props: PropsWithChildren) { - const { mockedResults, children } = props; - const query: any = () => Promise.resolve(mockedResults || {}); - const apiRegistry = TestApiRegistry.from([searchApiRef, { query }]); - return ; -} diff --git a/plugins/search-react/src/context/index.tsx b/plugins/search-react/src/context/index.tsx index 330da035d6..c805cacfc0 100644 --- a/plugins/search-react/src/context/index.tsx +++ b/plugins/search-react/src/context/index.tsx @@ -15,8 +15,16 @@ */ export { SearchContextProvider, useSearch } from './SearchContext'; -export type { SearchContextState } from './SearchContext'; +export type { + SearchContextProviderProps, + SearchContextState, + SearchContextValue, +} from './SearchContext'; export { - SearchContextProvider as SearchContextProviderForStorybook, - SearchApiProvider as SearchApiProviderForStorybook, + SearchContextProviderForStorybook, + SearchApiProviderForStorybook, +} from './SearchContextForStorybook.stories'; +export type { + SearchContextProviderForStorybookProps, + SearchApiProviderForStorybookProps, } from './SearchContextForStorybook.stories'; diff --git a/plugins/search-react/src/index.ts b/plugins/search-react/src/index.ts index 934cf2e9f1..8b250b6742 100644 --- a/plugins/search-react/src/index.ts +++ b/plugins/search-react/src/index.ts @@ -14,6 +14,12 @@ * limitations under the License. */ +/** + * Search Plugin frontend library + * + * @packageDocumentation + */ + export { searchApiRef } from './api'; export type { SearchApi } from './api'; export { @@ -22,4 +28,10 @@ export { SearchContextProviderForStorybook, SearchApiProviderForStorybook, } from './context'; -export type { SearchContextState } from './context'; +export type { + SearchContextProviderProps, + SearchContextState, + SearchContextValue, + SearchContextProviderForStorybookProps, + SearchApiProviderForStorybookProps, +} from './context'; diff --git a/scripts/api-extractor.ts b/scripts/api-extractor.ts index 946968c759..6d3ffb8eb2 100644 --- a/scripts/api-extractor.ts +++ b/scripts/api-extractor.ts @@ -257,6 +257,7 @@ const NO_WARNING_PACKAGES = [ 'plugins/scaffolder-common', 'plugins/search-backend-node', 'plugins/search-common', + 'plugins/search-react', 'plugins/techdocs', 'plugins/techdocs-backend', 'plugins/techdocs-node',