feat(search): show what the query search understood

Author: beanbocchi

src/api/generated/index.ts

@@ -934,6 +934,15 @@ export type ListingPage = {
     understood: string;
 };
 
+/**
+ * The moderation queue's page: the same cards, without the two search fields. That worklist takes no query, so there is nothing it could have understood, and a key that is always empty reads as a search a moderator could have run.
+ *
+ */
+export type ListingQueuePage = {
+    data: Array<Listing>;
+    meta: PageMeta;
+};
+
 /**
  * The slug a link carries: the listing's name, slugified and frozen at creation, with the listing's id on the end. The text in front is for the person reading the link and is not matched — renaming a listing does not rewrite links already shared, and a stale one still resolves because the id behind the last hyphen is what addresses the listing.
  *
@@ -3217,7 +3226,7 @@ export type GetAdminListingsResponses = {
     /**
      * OK
      */
-    200: ListingPage;
+    200: ListingQueuePage;
 };
 
 export type GetAdminListingsResponse = GetAdminListingsResponses[keyof GetAdminListingsResponses];

src/api/generated/types.gen.ts

@@ -0,0 +1,54 @@
+"use client";
+
+import type { SearchState } from "../_hooks/useSearchFilters";
+
+/**
+ * What the search made of a typed query, and the phrases that actually widened the
+ * ranking.
+ *
+ * `understood` is model-written prose, rendered as plain text and never as HTML — it
+ * stays hidden whenever the model had nothing usable to add: a browse with no query
+ * answers both fields empty, and a query the model could not read still gets its base
+ * retrieval rather than a claimed understanding it never reached. `probes` always
+ * includes the shopper's own words alongside whatever was corrected or expanded, so only
+ * the phrases that differ from what they typed are shown as chips — echoing their own
+ * words back as a "correction" would be exactly the coincidence this feature exists to
+ * explain away.
+ */
+export default function SearchUnderstanding({ search }: { search: SearchState }) {
+  const { understood, probes } = search.feed;
+  const own = search.query.trim().toLowerCase();
+  const corrected = probes.filter((probe) => probe.trim().toLowerCase() !== own);
+
+  if (!understood && corrected.length === 0) return null;
+
+  return (
+    <div className="mb-6 flex flex-col gap-2">
+      {understood && (
+        <p className="flex items-start gap-2 text-body-sm text-on-surface-variant">
+          <span
+            className="material-symbols-outlined text-base text-primary shrink-0"
+            aria-hidden="true"
+          >
+            auto_awesome
+          </span>
+          <span>{understood}</span>
+        </p>
+      )}
+
+      {corrected.length > 0 && (
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="text-label-sm text-on-surface-variant">Cũng tìm theo:</span>
+          {corrected.map((probe) => (
+            <span
+              key={probe}
+              className="rounded-full border border-outline-variant/30 bg-surface-container-low px-3 py-1 text-label-sm text-on-surface-variant"
+            >
+              {probe}
+            </span>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

src/app/search/_components/SearchUnderstanding.tsx

@@ -5,6 +5,7 @@ import ActiveFilterChips from "./_components/ActiveFilterChips";
 import SearchFilterPanel from "./_components/SearchFilterPanel";
 import SearchResults from "./_components/SearchResults";
 import SearchToolbar from "./_components/SearchToolbar";
+import SearchUnderstanding from "./_components/SearchUnderstanding";
 import { useSearchFilters } from "./_hooks/useSearchFilters";
 
 function SearchPageContent(): React.ReactElement {
@@ -17,6 +18,7 @@ function SearchPageContent(): React.ReactElement {
 
         <section className="md:col-span-9">
           <SearchToolbar search={search} />
+          <SearchUnderstanding search={search} />
           <ActiveFilterChips search={search} />
           <SearchResults search={search} />
         </section>

src/app/search/page.tsx

@@ -86,11 +86,17 @@ export function useListingsFeed(filters: ListingFilters = {}, enabled = true) {
 	})
 
 	const listings = useMemo(() => flattenPages(query.data), [query.data])
+	// `understood` and `probes` describe the query, not any one page of it, so every page
+	// repeats them and the first is enough. Both read as empty before the first page lands,
+	// same as an unset query — there is nothing yet to explain either way.
+	const firstPage = query.data?.pages[0]
 
 	return {
 		...query,
 		listings,
 		totalCount: totalCountOf(query.data),
+		understood: firstPage?.understood ?? "",
+		probes: firstPage?.probes ?? [],
 	}
 }