From f9037431423d6eec52174341651f11f607281760 Mon Sep 17 00:00:00 2001
From: Vincenzo Scamporlino <me@vinzscam.dev>
Date: Fri, 4 Feb 2022 20:53:01 +0100
Subject: [PATCH] Improve SearchContext api report

Signed-off-by: Vincenzo Scamporlino <me@vinzscam.dev>
---
 plugins/search/api-report.md                   | 18 +++++++++++-------
 .../components/SearchContext/SearchContext.tsx | 13 +++++++++----
 .../src/components/SearchContext/index.tsx     |  2 ++
 .../src/components/SearchModal/SearchModal.tsx | 13 +++++++++++++
 plugins/search/src/index.ts                    |  1 +
 5 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/plugins/search/api-report.md b/plugins/search/api-report.md
index a45f02564f..7533085fce 100644
--- a/plugins/search/api-report.md
+++ b/plugins/search/api-report.md
@@ -145,9 +145,17 @@ export const SearchContextProvider: ({
   initialState,
   children,
 }: React_2.PropsWithChildren<{
-  initialState?: SettableSearchContext | undefined;
+  initialState?: SearchContextState | undefined;
 }>) => JSX.Element;
 
+// @public
+export type SearchContextState = {
+  term: string;
+  types: string[];
+  filters: JsonObject;
+  pageCursor?: string;
+};
+
 // Warning: (ae-missing-release-tag) "SearchFilter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -201,6 +209,7 @@ export type SearchFilterWrapperProps = SearchFilterComponentProps & {
 // @public (undocumented)
 export const SearchModal: ({
   open,
+  hidden,
   toggleModal,
 }: SearchModalProps) => JSX.Element;
 
@@ -208,9 +217,8 @@ export const SearchModal: ({
 //
 // @public (undocumented)
 export interface SearchModalProps {
-  // (undocumented)
+  hidden?: boolean;
   open?: boolean;
-  // (undocumented)
   toggleModal: () => void;
 }
 
@@ -319,8 +327,4 @@ export type SidebarSearchProps = {
 //
 // @public (undocumented)
 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
 ```
diff --git a/plugins/search/src/components/SearchContext/SearchContext.tsx b/plugins/search/src/components/SearchContext/SearchContext.tsx
index df40f1de74..a9f42fe5ca 100644
--- a/plugins/search/src/components/SearchContext/SearchContext.tsx
+++ b/plugins/search/src/components/SearchContext/SearchContext.tsx
@@ -37,9 +37,14 @@ type SearchContextValue = {
   setPageCursor: React.Dispatch<React.SetStateAction<string | undefined>>;
   fetchNextPage?: React.DispatchWithoutAction;
   fetchPreviousPage?: React.DispatchWithoutAction;
-} & SettableSearchContext;
+} & SearchContextState;
 
-type SettableSearchContext = {
+/**
+ * The initial state of `SearchContextProvider`.
+ *
+ * @public
+ */
+export type SearchContextState = {
   term: string;
   types: string[];
   filters: JsonObject;
@@ -50,7 +55,7 @@ export const SearchContext = createContext<SearchContextValue | undefined>(
   undefined,
 );
 
-const searchInitialState: SettableSearchContext = {
+const searchInitialState: SearchContextState = {
   term: '',
   pageCursor: undefined,
   filters: {},
@@ -60,7 +65,7 @@ const searchInitialState: SettableSearchContext = {
 export const SearchContextProvider = ({
   initialState = searchInitialState,
   children,
-}: PropsWithChildren<{ initialState?: SettableSearchContext }>) => {
+}: PropsWithChildren<{ initialState?: SearchContextState }>) => {
   const searchApi = useApi(searchApiRef);
   const [pageCursor, setPageCursor] = useState<string | undefined>(
     initialState.pageCursor,
diff --git a/plugins/search/src/components/SearchContext/index.tsx b/plugins/search/src/components/SearchContext/index.tsx
index 682ade916f..8651e661c1 100644
--- a/plugins/search/src/components/SearchContext/index.tsx
+++ b/plugins/search/src/components/SearchContext/index.tsx
@@ -19,3 +19,5 @@ export {
   SearchContext,
   useSearch,
 } from './SearchContext';
+
+export type { SearchContextState } from './SearchContext';
diff --git a/plugins/search/src/components/SearchModal/SearchModal.tsx b/plugins/search/src/components/SearchModal/SearchModal.tsx
index ce3f51dac3..2a71e53ea8 100644
--- a/plugins/search/src/components/SearchModal/SearchModal.tsx
+++ b/plugins/search/src/components/SearchModal/SearchModal.tsx
@@ -38,8 +38,21 @@ import { Link, useContent } from '@backstage/core-components';
 import { rootRouteRef } from '../../plugin';
 
 export interface SearchModalProps {
+  /**
+   * If true, it renders the modal.
+   */
   open?: boolean;
+  /**
+   * This is supposed to be used together with the open prop.
+   * If `hidden` is true, it hides the modal.
+   * If `open` is false, the value of `hidden` has no effect on the modal.
+   * Use `open` for controlling whether the modal should be rendered or not.
+   */
   hidden?: boolean;
+  /**
+   * a function invoked when a search item is pressed or when the dialog
+   * should be closed.
+   */
   toggleModal: () => void;
 }
 
diff --git a/plugins/search/src/index.ts b/plugins/search/src/index.ts
index 99c3f5177b..18fbb2a713 100644
--- a/plugins/search/src/index.ts
+++ b/plugins/search/src/index.ts
@@ -32,6 +32,7 @@ export type {
   SearchBarProps,
 } from './components/SearchBar';
 export { SearchContextProvider, useSearch } from './components/SearchContext';
+export type { SearchContextState } from './components/SearchContext';
 export { SearchFilter, SearchFilterNext } from './components/SearchFilter';
 export type {
   SearchAutocompleteFilterProps,