doc

web/apps/photos/src/components/SearchBar.tsx

@@ -68,7 +68,12 @@ import { getAutoCompleteSuggestions } from "services/searchService";
 import { type Collection } from "types/collection";
 
 interface SearchBarProps {
+    /**
+     * `true` if the search bar is being shown when the gallery is already in
+     * "search mode".
+     */
     isInSearchMode: boolean;
+    /** Enter or exit search mode. */
     setIsInSearchMode: (v: boolean) => void;
     updateSearch: UpdateSearch;
     collections: Collection[];
@@ -80,6 +85,20 @@ export type UpdateSearch = (
     summary: SearchResultSummary,
 ) => void;
 
+/**
+ * The search bar is a styled "select" element that allow the user to type in
+ * the attached input field, and shows a list of matching options in a dropdown.
+ *
+ * When the search input is empty, it shows some general information in the
+ * dropdown instead (e.g. the ML indexing status).
+ *
+ * When the search input is not empty, it shows various {@link SearchOption}s,
+ * each of which is a possible suggestion for a search that the user might've
+ * intended. Each suggestion shows a count of matching files, and some previews.
+ *
+ * Selecting one of the these options causes the gallery to enter a "search
+ * mode", where it shows a filtered list of files that match that option.
+ */
 export const SearchBar: React.FC<SearchBarProps> = ({
     setIsInSearchMode,
     isInSearchMode,

web/packages/new/photos/services/search/types.ts

@@ -142,6 +142,10 @@ export interface SearchResultSummary {
 
 /**
  * An option shown in the the search bar's select dropdown.
+ *
+ * The option includes essential data that is necessary to show a corresponding
+ * entry in the dropdown. If the user selects the option, then we will re-run
+ * the search, using the data to filter the list of files shown to the user.
  */
 export interface SearchOption extends Suggestion {
     fileCount: number;