@stapel/search-react 0.11.0 → 0.12.0

package/src/headless/useFacetLabels.ts

@@ -0,0 +1,172 @@
+/**
+ * The HOST LABEL SEAM — the third source of a facet option's caption, and the
+ * only one that can reach a vocabulary.
+ *
+ * ── The defect ────────────────────────────────────────────────────────────
+ *
+ * A live classified deployment's category schema types `vendor`, `model`,
+ * `memory_size` and `color_ref_select` as `ref_select`: their config carries
+ * no `options` table at all, only a POINTER —
+ * `{"optionsRef": {"level": "Vendor", "vocabulary": "avito-phone-catalog"}}`.
+ * The words live in the vocabulary the pointer names, which is a different
+ * service with a different client. So the two label sources this pair already
+ * has both come up empty: the answer's `facet_labels` because the deployed
+ * server predates stapel-search 0.4.0 and sends no such key, and the schema
+ * because a pointer is not a table. The chips printed `apple`, `128-gb`,
+ * `chernyy` — storage slugs, at buyers.
+ *
+ * This pair must not grow a vocabulary client to fix that: it would tie every
+ * storefront's search to a service it may not run, and the host ALREADY has
+ * that client (`@stapel/attributes-react`'s `VocabularyClientProvider` is
+ * mounted for the composer). So the fetch is the host's and the discipline is
+ * this module's — the same division as `renderGeoFilter` and
+ * `renderCategoryFilter`, one seam lower because what crosses it is data
+ * rather than a control.
+ *
+ * ── Precedence, stated once ───────────────────────────────────────────────
+ *
+ *   1. the answer's `facet_labels`  — the server saw the write-time snapshot;
+ *   2. the feature def's inline `options` table — for the plain `select`
+ *      family, which carries its words with it;
+ *   3. this resolver;
+ *   4. the raw value.
+ *
+ * `buildFacetGroups` has already applied 1 and 2 by the time this hook runs,
+ * and it leaves an option it could not name with `label === value` — which is
+ * what makes "did anyone name this?" answerable without a second lookup. Only
+ * those values are asked about, so the host is never called for a value the
+ * server or the schema already captioned, and a resolver that returns nothing
+ * for a value leaves the raw value on screen. A chip that silently dropped an
+ * option would be worse than one showing a slug: the option is real, it has a
+ * count, and it is the only way to reach those documents.
+ *
+ * ── The fetch discipline ──────────────────────────────────────────────────
+ *
+ * TanStack Query, exactly like the pair's other three reads, and for the four
+ * reasons that made it right there:
+ *
+ *  - **batched per group.** One call per facet slug carrying every unresolved
+ *    value of it, not one call per chip.
+ *  - **cached.** `staleTime: Infinity` — a vocabulary term's caption changes
+ *    when somebody edits the catalogue, not between two clicks on a filter.
+ *  - **deduplicated.** The chip row, the filter panel and the page's layout
+ *    probe each call `useFacetPanel`, so three components ask for the same
+ *    group's captions in one render pass; one query key means one request.
+ *  - **aborted on supersession.** The `signal` is the query's own, so a
+ *    resolver that honours it stops a request whose answer nobody will read.
+ */
+import { useQueries } from "@tanstack/react-query";
+import { mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { searchQueryKeys } from "../model/queryKeys.js";
+import type { FacetGroup } from "../state/facets.js";
+
+/** What the host is asked to name. */
+export interface FacetLabelRequest {
+  /** The facet slug — `vendor`, `color_ref_select`. */
+  readonly slug: string;
+  /**
+   * The category's own def for the slug, when the host supplied a schema.
+   * It carries the `optionsRef` pointer (vocabulary + level) a resolver needs
+   * to know WHICH vocabulary these codes belong to, so a host does not have to
+   * keep a second copy of the schema to answer.
+   */
+  readonly feature: FeatureDef | undefined;
+  /**
+   * The values nobody has named yet, sorted. Only the unresolved ones: a
+   * resolver is never asked about a value the server or the schema captioned.
+   */
+  readonly values: readonly string[];
+}
+
+/**
+ * A host's answer: `{value: caption}`.
+ *
+ * Partial answers are the expected case, not an error — a code the vocabulary
+ * no longer holds simply is not in the map, and its chip keeps printing the
+ * raw value. Returning `{}` is a legitimate "I cannot name any of these".
+ */
+export type FacetLabelResolver = (
+  request: FacetLabelRequest,
+  options: { readonly signal: AbortSignal }
+) => Promise<Readonly<Record<string, string>>>;
+
+/** One frozen empty list, so a render with no unresolved values is stable. */
+const NO_REQUESTS: readonly FacetLabelRequest[] = [];
+
+/** The values of one group nobody has named — see the precedence note above. */
+function unresolvedValues(group: FacetGroup): readonly string[] {
+  return group.options
+    .filter((option) => option.label === option.value)
+    .map((option) => option.value)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function isCaptionMap(value: unknown): value is Readonly<Record<string, string>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Fill in what the server and the schema could not name, through the host.
+ *
+ * Returns the groups UNCHANGED — same object identity — when there is no
+ * resolver or nothing came back, so a page with the seam unwired pays neither
+ * a request nor a re-render.
+ */
+export function useHostFacetLabels(
+  groups: LoadState<readonly FacetGroup[]>,
+  resolve: FacetLabelResolver | undefined,
+  locale: string | undefined
+): LoadState<readonly FacetGroup[]> {
+  const requests: readonly FacetLabelRequest[] =
+    resolve === undefined || groups.status !== "ready"
+      ? NO_REQUESTS
+      : groups.data
+          .map((group) => ({
+            slug: group.slug,
+            feature: group.feature,
+            values: unresolvedValues(group),
+          }))
+          .filter((request) => request.values.length > 0);
+
+  const answers = useQueries({
+    queries: requests.map((request) => ({
+      queryKey: searchQueryKeys.facetLabels(request.slug, request.values, locale),
+      queryFn: async ({ signal }: { signal: AbortSignal }): Promise<unknown> =>
+        resolve === undefined ? {} : await resolve(request, { signal }),
+      staleTime: Number.POSITIVE_INFINITY,
+      // A vocabulary that answered 500 answers 500 again a millisecond later,
+      // and three retries only delay the chip's raw value by three round
+      // trips — the same discipline the pair's other reads keep.
+      retry: false,
+    })),
+  });
+
+  const captions = new Map<string, Readonly<Record<string, string>>>();
+  requests.forEach((request, index) => {
+    const data = answers[index]?.data;
+    if (isCaptionMap(data)) captions.set(request.slug, data);
+  });
+  if (captions.size === 0) return groups;
+
+  return mapLoad(groups, (list) =>
+    list.map((group) => {
+      const named = captions.get(group.slug);
+      if (named === undefined) return group;
+      return {
+        ...group,
+        options: group.options.map((option) => {
+          // Precedence again, enforced rather than assumed: an option whose
+          // label already differs from its value was named by the server or
+          // the schema, and the host does not get to overwrite either.
+          if (option.label !== option.value) return option;
+          const caption = named[option.value];
+          return caption === undefined || caption.length === 0
+            ? option
+            : { ...option, label: caption };
+        }),
+      };
+    })
+  );
+}

package/src/headless/useSearchBox.ts

@@ -21,10 +21,36 @@
  *
  * The suggestion list is asked for the DEBOUNCED prefix, not the draft — one
  * request per pause, not per keystroke, on an endpoint the backend throttles.
+ *
+ * ── The box reaches the CATALOGUE, not only the titles ────────────────────
+ *
+ * stapel-search 0.7.0 answers `/suggest` with two halves. Until it did, typing
+ * a word that names a section of the catalogue answered listing titles and
+ * nothing else: on a live classified deployment the search field could not
+ * reach a category at all, and the owner's own navigation canon rules out both
+ * of the usual workarounds — a picker, and a client-side typeahead over the
+ * whole tree.
+ *
+ * The server's answer is neither, and it carries the one thing a client-side
+ * matcher can never have: the number of LIVE listings behind each destination,
+ * computed as one aggregate over the index and equal to what `/query` reports
+ * for the same category. That number is what tells "Menswear / Shorts" from
+ * "Childrenswear / Shorts".
+ *
+ * Everything here is absent-safe. A server that predates 0.7.0 sends no
+ * `categories` key, `suggestCategories` is empty, and the box behaves exactly
+ * as it did — which is not a hypothetical: the key appeared mid-session on a
+ * stand that was redeployed underneath a running client.
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { loadStateFromQuery, mapLoad } from "@stapel/core";
 import type { LoadState } from "@stapel/core";
+import {
+  SUGGEST_DEGRADED_CATEGORIES,
+  SUGGEST_DEGRADED_ROLLUP,
+  suggestTerms,
+} from "../api/types.js";
+import type { SuggestAnswer, SuggestCategory } from "../api/types.js";
 import { useSearchState } from "./SearchStateProvider.js";
 import { useSuggest } from "../model/queries.js";
 import {
@@ -55,6 +81,42 @@ export interface SearchBoxBag {
   readonly suggestState: LoadState<readonly string[]>;
   /** A suggestion request is in flight for a prefix nothing is shown for yet. */
   readonly suggestLoading: boolean;
+  /**
+   * CATEGORY destinations for the typed prefix, server-ranked by live listing
+   * count — the primary half of the answer (stapel-search 0.7.0).
+   *
+   * Empty on a server that sends no `categories` key, and empty when the
+   * server could not reach a category provider: see
+   * {@link SearchBoxBag.categoriesUnavailable} for why a surface must tell
+   * those two apart from "nothing matched".
+   *
+   * A category with a count of `0` is already filtered out — see
+   * {@link SearchBoxBag.categoryCountsUnknown}.
+   */
+  readonly categories: readonly SuggestCategory[];
+  /**
+   * The server HAS no category provider for this answer
+   * (`degraded: ["category_suggestions"]`), so `categories` being empty says
+   * nothing about the catalogue.
+   *
+   * A surface must render no group at all rather than an empty one: a heading
+   * over nothing is the box telling a person the catalogue has no section by
+   * that name, which is a claim this answer did not make. It is deliberately
+   * NOT a banner either — the reader is mid-word, the terms half still
+   * answers, and a provider being down is the operator's business, the same
+   * ruling `degradationAudience` already applies to an engine shortfall.
+   */
+  readonly categoriesUnavailable: boolean;
+  /**
+   * The counts on {@link SearchBoxBag.categories} are not answers
+   * (`degraded: ["category_rollup"]`): with no ancestry every stored path is
+   * one segment long, so every count would read `0` for a mechanical reason.
+   *
+   * The rows are still real destinations and are still offered; a surface
+   * prints the path and omits the number, because a catalogue of zeros is
+   * worse than a list with no counts.
+   */
+  readonly categoryCountsUnknown: boolean;
   /** Characters a prefix needs before the index is asked. */
   readonly minSuggestChars: number;
   readonly maxLength: number;
@@ -65,6 +127,25 @@ export interface SearchBoxBag {
   submit(value?: string): void;
   /** Empty the box AND the search (an empty `q` is a valid browse). */
   clear(): void;
+  /**
+   * Follow a category suggestion: narrow the SERP to that section.
+   *
+   * Two decisions, both load-bearing.
+   *
+   * The `category` parameter is set to the server's own
+   * {@link SuggestCategory.category} string, VERBATIM. The server joins the
+   * ancestry itself precisely so a client cannot invent a different join and
+   * silently miss, so nothing here rebuilds it from the path or the slug.
+   *
+   * The typed text is CLEARED in the same write. The row promised a count —
+   * "Menswear / Shorts, 1 240 listings" — and that number is the
+   * section's, not the section's intersected with a title search for the word
+   * that found it. Keeping `q` would land a person on strictly fewer results
+   * than the row they tapped had just quoted, which is the row lying about
+   * where it goes. One `patch` call, so it is also one history entry: Back
+   * returns to the search the person typed.
+   */
+  chooseCategory(category: SuggestCategory): void;
 }
 
 export interface UseSearchBoxOptions {
@@ -81,8 +162,39 @@ export interface UseSearchBoxOptions {
 /** One frozen empty list, so a render with no suggestions is a stable value. */
 const NO_SUGGESTIONS: readonly string[] = [];
 
+/** The same, for the categories half. */
+const NO_CATEGORIES: readonly SuggestCategory[] = [];
+
+/** Does this answer name a shortfall? Absent-safe on every older server. */
+function degradedWith(answer: SuggestAnswer | undefined, literal: string): boolean {
+  return answer?.degraded?.includes(literal) === true;
+}
+
+/**
+ * The destinations worth offering out of one answer.
+ *
+ * A category with a count of `0` is a section with nothing in it: following it
+ * lands the buyer on an empty SERP, which is a dead end dressed as a
+ * destination — and the server does return those (it reads the count with a
+ * `0` default and ranks them last), so somebody has to drop them.
+ *
+ * The one exception is `category_rollup`, where EVERY count is `0` because the
+ * ancestry never arrived rather than because the sections are empty. Filtering
+ * on the count there would delete the whole group for a reason that has
+ * nothing to do with what is in the catalogue, so the rows are kept and the
+ * numbers are what the surface omits.
+ */
+export function offerableCategories(
+  answer: SuggestAnswer | undefined
+): readonly SuggestCategory[] {
+  const categories = answer?.categories;
+  if (categories === undefined || categories.length === 0) return NO_CATEGORIES;
+  if (degradedWith(answer, SUGGEST_DEGRADED_ROLLUP)) return categories;
+  return categories.filter((category) => category.count > 0);
+}
+
 export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
-  const { state, setText } = useSearchState();
+  const { state, setText, patch } = useSearchState();
   const committed = state.q;
   const debounceMs = options.debounceMs ?? SEARCH_BOX_DEBOUNCE_MS;
 
@@ -168,10 +280,21 @@ export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
     enabled: options.suggest !== false,
   });
 
-  const suggestState = mapLoad(
-    loadStateFromQuery(suggest),
-    (data) => data.items as readonly string[]
-  );
+  const suggestState = mapLoad(loadStateFromQuery(suggest), suggestTerms);
+
+  // The READY answer only. A category row is a navigation control, and one
+  // rendered out of a stale answer would send a person somewhere the current
+  // prefix never named.
+  const answer = suggest.data;
+  const categories = offerableCategories(answer);
+
+  const chooseCategory = (category: SuggestCategory): void => {
+    setDraftState("");
+    cancel();
+    // One write, so one history entry — see `SearchBoxBag.chooseCategory` for
+    // why the text goes with it.
+    patch({ q: "", category: category.category });
+  };
 
   return {
     draft,
@@ -180,10 +303,14 @@ export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
     suggestions: suggestState.status === "ready" ? suggestState.data : NO_SUGGESTIONS,
     suggestState,
     suggestLoading: suggest.isLoading && suggest.fetchStatus === "fetching",
+    categories,
+    categoriesUnavailable: degradedWith(answer, SUGGEST_DEGRADED_CATEGORIES),
+    categoryCountsUnknown: degradedWith(answer, SUGGEST_DEGRADED_ROLLUP),
     minSuggestChars: SUGGEST_MIN_CHARS,
     maxLength: SEARCH_QUERY_MAX_CHARS,
     setDraft,
     submit,
     clear,
+    chooseCategory,
   };
 }

package/src/i18n/es.ts

@@ -46,6 +46,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.box.submit": "Buscar",
   "search.box.clear": "Borrar la búsqueda",
   "search.box.suggestions": "Sugerencias",
+  "search.box.categories": "Secciones",
+  "search.box.category_count.one": "{count} anuncio",
+  "search.box.category_count.other": "{count} anuncios",
 
   "search.sort.label": "Orden",
   "search.sort.relevance": "Más relevantes",
@@ -93,6 +96,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.filters.dismiss": "Cerrar los filtros",
   "search.filters.chips_label": "Filtros",
   "search.filters.all": "Todos los filtros",
+  "search.filters.short": "Filtros",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Categoría",
@@ -150,6 +154,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.ranking.inactive": "No aplicado: {reason}",
   "search.ranking.notes": "Notas",
   "search.ranking.link": "Cómo se ordenan estos resultados",
+
+  "search.nav.results": "Buscar",
+  "search.nav.ranking": "Orden de resultados",
+  "search.nav.ranking.short": "Orden",
 };
 
 /** Register the es bundle. Call AFTER `registerSearchI18n`. */

package/src/i18n/keys.ts

@@ -64,6 +64,22 @@ export const SEARCH_I18N_KEYS = {
   boxClear: "search.box.clear",
   /** Accessible name of the suggestion list under the box. */
   boxSuggestions: "search.box.suggestions",
+  /**
+   * The heading over the CATEGORY half of the type-ahead (stapel-search
+   * 0.7.0). The rows under it are DESTINATIONS — a section of the catalogue —
+   * and not, like everything else in the menu, another set of words to search
+   * for; a group with no heading would read as more of the same.
+   */
+  boxCategories: "search.box.categories",
+  /**
+   * "1 240 listings" beside a category row — how many LIVE listings a buyer
+   * would see there, the same number the SERP reports for it.
+   *
+   * A PLURAL FAMILY: render with `tPlural`, never `t`. It counts a noun in
+   * words, so Russian needs its four endings and a single string would be
+   * right only for 5-20 — the exact defect the results count already fixed.
+   */
+  boxCategoryCount: "search.box.category_count",
 
   // ── sort ─────────────────────────────────────────────────────────────────
   sortLabel: "search.sort.label",
@@ -129,6 +145,9 @@ export const SEARCH_I18N_KEYS = {
   /** The leading, icon-only chip: the whole panel. Icon-only means the name
    * exists ONLY here, so this key is the control's entire accessibility. */
   filtersAll: "search.filters.all",
+  /** The same door, named for a 390px row: the location line's trailing link
+   * sits beside a place name and cannot spend six characters on "All". */
+  filtersShort: "search.filters.short",
   /** A chip filtering on more than one value: "Bosch, +2". Not a plural
    * family — nothing is being counted in words. */
   filtersChipMore: "search.filters.chip_more",
@@ -207,6 +226,34 @@ export const SEARCH_I18N_KEYS = {
   rankingInactive: "search.ranking.inactive",
   rankingNotes: "search.ranking.notes",
   rankingLink: "search.ranking.link",
+
+  // ── nav (the destination's own name, not the page's heading) ─────────────
+  /**
+   * What the MENU calls the results screen.
+   *
+   * Separate from `search.results.title` on purpose. That key captions the
+   * list of matches — a heading over rows, which is why it reads "Results" —
+   * and a menu entry pointing at `/s` labelled "Results" tells a visitor
+   * nothing about where they would be going: results of what? The destination
+   * is the search itself. One key, one job; a translator asked to make
+   * "Results" work as both a page heading and a menu label has to pick which
+   * one to get wrong.
+   */
+  navResults: "search.nav.results",
+  /** The menu name of the P2B disclosure PAGE — see {@link navResults} for
+   * why it is not `search.ranking.title`, which is the page's own heading and
+   * a whole sentence. */
+  navRanking: "search.nav.ranking",
+  /**
+   * The compact form for a phone dock — see `NavEntry.shortLabelKey`. A
+   * five-cell dock at 390px gives a destination roughly ten characters, and
+   * "Ranking disclosure" ellipsizes to a fragment there.
+   *
+   * `search.nav.results` needs no short form: it is already one word in every
+   * locale this pair ships, and declaring a short key identical to the long
+   * one only gives a translator two strings to keep in sync.
+   */
+  navRankingShort: "search.nav.ranking.short",
 } as const;
 
 export type SearchI18nKey =
@@ -233,6 +280,7 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.resultsCountExact,
   SEARCH_I18N_KEYS.filtersShowCount,
   SEARCH_I18N_KEYS.filtersShowCountAtLeast,
+  SEARCH_I18N_KEYS.boxCategoryCount,
 ];
 
 /**
@@ -276,6 +324,9 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.box.submit": "Search",
   "search.box.clear": "Clear the search",
   "search.box.suggestions": "Suggestions",
+  "search.box.categories": "Sections",
+  "search.box.category_count.one": "{count} listing",
+  "search.box.category_count.other": "{count} listings",
 
   "search.sort.label": "Sort",
   "search.sort.relevance": "Most relevant",
@@ -323,6 +374,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.filters.dismiss": "Close the filters",
   "search.filters.chips_label": "Filters",
   "search.filters.all": "All filters",
+  "search.filters.short": "Filters",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Category",
@@ -379,6 +431,10 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.ranking.inactive": "Not applied: {reason}",
   "search.ranking.notes": "Notes",
   "search.ranking.link": "How these results are ordered",
+
+  "search.nav.results": "Search",
+  "search.nav.ranking": "Ranking disclosure",
+  "search.nav.ranking.short": "Ranking",
 };
 
 /**

package/src/i18n/ru.ts

@@ -69,6 +69,11 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.box.submit": "Найти",
   "search.box.clear": "Очистить запрос",
   "search.box.suggestions": "Подсказки",
+  "search.box.categories": "Разделы",
+  "search.box.category_count.one": "{count} объявление",
+  "search.box.category_count.few": "{count} объявления",
+  "search.box.category_count.many": "{count} объявлений",
+  "search.box.category_count.other": "{count} объявления",
 
   "search.sort.label": "Сортировка",
   "search.sort.relevance": "По релевантности",
@@ -120,6 +125,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.filters.dismiss": "Закрыть фильтры",
   "search.filters.chips_label": "Фильтры",
   "search.filters.all": "Все фильтры",
+  "search.filters.short": "Фильтры",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Категория",
@@ -177,6 +183,10 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.ranking.inactive": "Не применяется: {reason}",
   "search.ranking.notes": "Примечания",
   "search.ranking.link": "Как упорядочены результаты",
+
+  "search.nav.results": "Поиск",
+  "search.nav.ranking": "Порядок результатов",
+  "search.nav.ranking.short": "Порядок",
 };
 
 /** Register the ru bundle. Call AFTER `registerSearchI18n` so it layers over

package/src/index.ts

@@ -44,7 +44,12 @@
 export { createSearchApi, searchQueryParams } from "./api/searchApi.js";
 export type { SearchApi } from "./api/searchApi.js";
 export type { Schemas } from "./api/types.js";
-export { SEARCH_SORTS } from "./api/types.js";
+export {
+  SEARCH_SORTS,
+  SUGGEST_DEGRADED_CATEGORIES,
+  SUGGEST_DEGRADED_ROLLUP,
+  suggestTerms,
+} from "./api/types.js";
 export type {
   FacetMeta,
   FacetSelection,
@@ -59,6 +64,9 @@ export type {
   SearchQueryState,
   SearchRange,
   SearchResponse,
+  SuggestAnswer,
+  SuggestCategory,
+  SuggestCategoryMatch,
   SuggestParams,
   SuggestResponse,
 } from "./api/types.js";
@@ -100,7 +108,12 @@ export type {
   SearchDegradationAudience,
 } from "./state/degradations.js";
 
-export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
+export {
+  FACETABLE_FEATURE_TYPES,
+  buildFacetGroups,
+  facetOptionLabel,
+  isFacetableFeature,
+} from "./state/facets.js";
 export type {
   BuildFacetGroupsInput,
   FacetGroup,
@@ -157,8 +170,13 @@ export { SearchResults } from "./headless/SearchResults.js";
 export type { SearchPageInfo, SearchResultsBag } from "./headless/SearchResults.js";
 export { FacetPanel, useFacetPanel } from "./headless/FacetPanel.js";
 export type { FacetPanelBag } from "./headless/FacetPanel.js";
+export { useHostFacetLabels } from "./headless/useFacetLabels.js";
+export type {
+  FacetLabelRequest,
+  FacetLabelResolver,
+} from "./headless/useFacetLabels.js";
 export { useAppliedSort } from "./headless/useAppliedSort.js";
-export { useSearchBox } from "./headless/useSearchBox.js";
+export { offerableCategories, useSearchBox } from "./headless/useSearchBox.js";
 export type { SearchBoxBag, UseSearchBoxOptions } from "./headless/useSearchBox.js";
 export { countQueryState, useSearchCount } from "./headless/useSearchCount.js";
 export type {

package/src/model/queries.ts

@@ -6,7 +6,7 @@ import type {
   RankingResponse,
   SearchQueryState,
   SearchResponse,
-  SuggestResponse,
+  SuggestAnswer,
 } from "../api/types.js";
 import { SUGGEST_MAX_LIMIT, SUGGEST_MIN_CHARS } from "../state/limits.js";
 import { useSearchApi } from "./context.js";
@@ -63,11 +63,12 @@ export function useSearchQuery(
 }
 
 /**
- * Title prefixes from the index, for the search box's typeahead.
+ * What the box offers under the cursor: CATEGORIES and title prefixes.
  *
  * Not from a query log: stapel-search keeps none, which is a privacy decision
- * before it is a product one (`services.suggest`). So the list is what exists
- * in the catalogue, and choosing one is always a search that has results.
+ * before it is a product one (`services.suggest`). So both halves are what
+ * exists in the catalogue — choosing a term is always a search that has
+ * results, and choosing a category is always a section that exists.
  *
  * `enabled` is the debounce's partner, not its replacement: the CALLER holds a
  * debounced prefix (see `useSearchBox`) and this hook refuses to ask about a
@@ -83,7 +84,7 @@ export function useSuggest(params: {
   readonly q: string;
   readonly limit?: number;
   readonly enabled?: boolean;
-}): UseQueryResult<SuggestResponse, StapelApiError> {
+}): UseQueryResult<SuggestAnswer, StapelApiError> {
   const api = useSearchApi();
   const q = params.q.trim();
   const limit = params.limit;

package/src/model/queryKeys.ts

@@ -32,6 +32,22 @@ export const searchQueryKeys: {
   query(
     params: SearchQueryKeyParams
   ): readonly ["search", "query", SearchQueryKeyParams];
+  /**
+   * One group's captions from the HOST's resolver — the seam that names a
+   * vocabulary-backed facet value on a server too old to caption it itself.
+   *
+   * Keyed on the slug, the values asked about and the locale. The values are
+   * SORTED by the caller before they get here: the same group arrives in
+   * count order, and count order changes on every click, so an unsorted key
+   * would re-ask the host for the same words each time a sibling facet moved.
+   * The locale is in the key because a caption is copy — one cache entry per
+   * language, never one shared between two.
+   */
+  facetLabels(
+    slug: string,
+    values: readonly string[],
+    locale?: string
+  ): readonly ["search", "facet-labels", string, readonly string[], string | null];
   /** The P2B disclosure. `type` is optional on the endpoint; normalized to
    * `null` so an absent type and an explicit `undefined` cannot cache twice. */
   ranking(type?: string): readonly ["search", "ranking", string | null];
@@ -43,6 +59,13 @@ export const searchQueryKeys: {
 } = {
   all: [ROOT],
   query: (params) => [ROOT, "query", params],
+  facetLabels: (slug, values, locale) => [
+    ROOT,
+    "facet-labels",
+    slug,
+    values,
+    locale ?? null,
+  ],
   ranking: (type) => [ROOT, "ranking", type ?? null],
   suggest: (type, q, limit) => [ROOT, "suggest", type, q, limit ?? null],
 };