@stapel/search-react 0.4.0 → 0.8.0

package/src/headless/useSearchBox.ts

@@ -0,0 +1,189 @@
+/**
+ * The query box, headless — the state machine behind `<SearchBox>`.
+ *
+ * ── The one legitimate second copy of the state ────────────────────────────
+ *
+ * This pair's rule is that the URL is the state and no component keeps a copy.
+ * A text input is the single exception the rule has to make: what a person has
+ * TYPED is not yet what they have SEARCHED for, and committing every keystroke
+ * to the URL would make the address bar (and the request, and the query cache)
+ * chase the keyboard. So the draft lives here, for as long as it takes to stop
+ * typing, and the URL is still the only place a SEARCH is recorded.
+ *
+ * Two properties keep that honest:
+ *
+ *  1. **The URL wins whenever it moves on its own.** Back, a shared link
+ *     opening, a host calling `setText` elsewhere — the draft is reset to the
+ *     committed `q`. The box can never show a word the results are not about.
+ *  2. **Committing REPLACES the history entry** (`setText` already does), so a
+ *     ten-letter word is one entry and Back still removes the last FILTER
+ *     rather than the last letter.
+ *
+ * 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.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { useSearchState } from "./SearchStateProvider.js";
+import { useSuggest } from "../model/queries.js";
+import {
+  SEARCH_BOX_DEBOUNCE_MS,
+  SEARCH_BOX_SUGGEST_DEBOUNCE_MS,
+  SEARCH_QUERY_MAX_CHARS,
+  SUGGEST_MIN_CHARS,
+} from "../state/limits.js";
+
+/** What a query box needs to read and move the search text. */
+export interface SearchBoxBag {
+  /** What is in the input right now. */
+  readonly draft: string;
+  /** What the URL — and therefore the results — is about. */
+  readonly committed: string;
+  /** The draft has not reached the URL yet (a search is about to run). */
+  readonly pending: boolean;
+  /**
+   * Title prefixes for the typeahead — the READY answer only.
+   *
+   * A typeahead has no surface for "we could not fetch suggestions": the box
+   * must stay typeable and a person is mid-word. So a failed or in-flight
+   * suggest shows nothing, and the three answers stay distinguishable in
+   * {@link SearchBoxBag.suggestState} for a skin that wants to say more.
+   */
+  readonly suggestions: readonly string[];
+  /** The suggest read as a state, unflattened. */
+  readonly suggestState: LoadState<readonly string[]>;
+  /** A suggestion request is in flight for a prefix nothing is shown for yet. */
+  readonly suggestLoading: boolean;
+  /** Characters a prefix needs before the index is asked. */
+  readonly minSuggestChars: number;
+  readonly maxLength: number;
+
+  /** Type. Commits after {@link SEARCH_BOX_DEBOUNCE_MS} of quiet. */
+  setDraft(next: string): void;
+  /** Commit now — Enter, the Search button, or picking a suggestion. */
+  submit(value?: string): void;
+  /** Empty the box AND the search (an empty `q` is a valid browse). */
+  clear(): void;
+}
+
+export interface UseSearchBoxOptions {
+  readonly debounceMs?: number;
+  /** Ask the index for prefixes. Default `true`. */
+  readonly suggest?: boolean;
+  /** Quiet time before the index is asked (default
+   * {@link SEARCH_BOX_SUGGEST_DEBOUNCE_MS}). */
+  readonly suggestDebounceMs?: number;
+  /** How many suggestions to ask for (backend clamps to 25). Default 8. */
+  readonly suggestLimit?: number;
+}
+
+/** One frozen empty list, so a render with no suggestions is a stable value. */
+const NO_SUGGESTIONS: readonly string[] = [];
+
+export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
+  const { state, setText } = useSearchState();
+  const committed = state.q;
+  const debounceMs = options.debounceMs ?? SEARCH_BOX_DEBOUNCE_MS;
+
+  const [draft, setDraftState] = useState(committed);
+  // What the URL said the last time we looked. When it changes underneath us
+  // — Back, a shared link, a host control — the draft follows it; when it
+  // changes BECAUSE we committed, `draft === committed` already and the reset
+  // is a no-op.
+  const lastCommitted = useRef(committed);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  if (lastCommitted.current !== committed) {
+    lastCommitted.current = committed;
+    if (draft !== committed) setDraftState(committed);
+  }
+
+  const cancel = useCallback((): void => {
+    if (timer.current !== null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  }, []);
+
+  // A pending commit must not fire into an unmounted tree, and a box that is
+  // unmounted mid-word has not searched for that word.
+  useEffect(() => cancel, [cancel]);
+
+  const commit = useCallback(
+    (value: string): void => {
+      cancel();
+      if (value !== committed) setText(value);
+    },
+    [cancel, committed, setText]
+  );
+
+  const setDraft = useCallback(
+    (next: string): void => {
+      const clipped = next.slice(0, SEARCH_QUERY_MAX_CHARS);
+      setDraftState(clipped);
+      cancel();
+      timer.current = setTimeout(() => {
+        timer.current = null;
+        if (clipped !== committed) setText(clipped);
+      }, debounceMs);
+    },
+    [cancel, committed, debounceMs, setText]
+  );
+
+  const submit = useCallback(
+    (value?: string): void => {
+      const next = (value ?? draft).slice(0, SEARCH_QUERY_MAX_CHARS);
+      setDraftState(next);
+      commit(next);
+    },
+    [commit, draft]
+  );
+
+  const clear = useCallback((): void => {
+    setDraftState("");
+    commit("");
+  }, [commit]);
+
+  // The index is asked about the SETTLED prefix, never the keystroke: one
+  // request per pause on an endpoint the backend throttles. `useSuggest` then
+  // refuses anything below `SUGGEST_MIN_CHARS` and keys the rest by prefix, so
+  // backspacing to a prefix already asked about costs nothing.
+  const suggestDebounceMs =
+    options.suggestDebounceMs ?? SEARCH_BOX_SUGGEST_DEBOUNCE_MS;
+  const [suggestPrefix, setSuggestPrefix] = useState(committed);
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      setSuggestPrefix(draft);
+    }, suggestDebounceMs);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [draft, suggestDebounceMs]);
+
+  const suggest = useSuggest({
+    type: state.type,
+    q: suggestPrefix,
+    ...(options.suggestLimit !== undefined ? { limit: options.suggestLimit } : {}),
+    enabled: options.suggest !== false,
+  });
+
+  const suggestState = mapLoad(
+    loadStateFromQuery(suggest),
+    (data) => data.items as readonly string[]
+  );
+
+  return {
+    draft,
+    committed,
+    pending: draft !== committed,
+    suggestions: suggestState.status === "ready" ? suggestState.data : NO_SUGGESTIONS,
+    suggestState,
+    suggestLoading: suggest.isLoading && suggest.fetchStatus === "fetching",
+    minSuggestChars: SUGGEST_MIN_CHARS,
+    maxLength: SEARCH_QUERY_MAX_CHARS,
+    setDraft,
+    submit,
+    clear,
+  };
+}

package/src/i18n/es.ts

@@ -39,6 +39,13 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.results.distance_km": "a {km} km",
   "search.results.untitled": "Sin título",
   "search.results.open": "Abrir",
+  "search.results.image_alt": "Foto de {title}",
+
+  "search.box.label": "Buscar",
+  "search.box.placeholder": "¿Qué estás buscando?",
+  "search.box.submit": "Buscar",
+  "search.box.clear": "Borrar la búsqueda",
+  "search.box.suggestions": "Sugerencias",
 
   "search.sort.label": "Orden",
   "search.sort.relevance": "Más relevantes",
@@ -48,6 +55,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.sort.distance": "Más cercanos",
   "search.sort.server_chose": "Ordenado por {sort}",
 
+  "search.view.label": "Vista",
+  "search.view.list": "Lista",
+  "search.view.grid": "Cuadrícula",
+
   "search.facets.title": "Filtros",
   "search.facets.loading": "Cargando filtros…",
   "search.facets.load_failed": "No pudimos cargar los filtros.",
@@ -64,21 +75,52 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.range_from": "Desde",
   "search.facets.range_to": "Hasta",
   "search.facets.range_apply": "Aplicar",
+  "search.facets.range_clear": "Quitar",
+  "search.facets.range_from_aria": "{feature}, desde",
+  "search.facets.range_to_aria": "{feature}, hasta",
+  "search.facets.show_all": "Ver todos ({count})",
+  "search.facets.show_less": "Ver menos",
+  "search.facets.range_invalid":
+    "«Desde» es mayor que «hasta», así que nada podría coincidir. Intercámbialos para aplicar el rango.",
+
+  "search.filters.open": "Filtros ({count})",
+  "search.filters.apply": "Ver resultados",
+  "search.filters.show_count.one": "Ver {count} resultado",
+  "search.filters.show_count.other": "Ver {count} resultados",
+  "search.filters.show_count_at_least.one": "Ver {count}+ resultado",
+  "search.filters.show_count_at_least.other": "Ver {count}+ resultados",
+  "search.filters.dismiss": "Cerrar los filtros",
+  "search.filters.chips_label": "Filtros",
+  "search.filters.all": "Todos los filtros",
+  "search.filters.chip_more": ", +{count}",
+
+  "search.category.title": "Categoría",
+  "search.category.clear": "Buscar en todo el catálogo",
+  "search.category.current": "Buscando dentro de {path}",
+
+  "search.language.label": "Idioma de la consulta",
+  "search.language.any": "Cualquier idioma",
+
+  "search.limit.label": "Por página",
+  "search.limit.option": "{count} por página",
+  "search.limit.from_link": "Este enlace fija su propio tamaño de página.",
 
   "search.geo.title": "Ubicación",
   "search.geo.radius_km": "A menos de {km} km",
+  "search.geo.radius_label": "Radio, km",
   "search.geo.clear": "En cualquier lugar",
   "search.geo.box": "Dentro del área mostrada",
   "search.geo.center": "Cerca de {lat}, {lon}",
 
   "search.url.issues_title": "Parte de este enlace no se pudo leer",
-  "search.url.issue.not_a_number": "{param} no es un número y se ignoró",
+  "search.url.issue.not_a_number":
+    "«{param}» en este enlace no es un número, así que se ignoró",
   "search.url.issue.geo_incomplete":
-    "la ubicación necesita lat y lon, así que se ignoró",
+    "la ubicación de este enlace está incompleta, así que se ignoró",
   "search.url.issue.bbox_malformed":
-    "el área necesita cuatro números (minLat,minLon,maxLat,maxLon) y se ignoró",
+    "el área del mapa de este enlace está incompleta, así que se ignoró",
   "search.url.issue.range_malformed":
-    "{param} no es un rango from..to y se ignoró",
+    "al rango «{param}» de este enlace le faltan números, así que se ignoró",
 
   "search.degraded.title": "Lo que esta búsqueda no pudo hacer",
   "search.degraded.typo_tolerance":

package/src/i18n/keys.ts

@@ -54,6 +54,16 @@ export const SEARCH_I18N_KEYS = {
   resultsDistanceKm: "search.results.distance_km",
   resultsUntitled: "search.results.untitled",
   resultsOpen: "search.results.open",
+  /** Alt text for the card photo — the card's own title, in a sentence. */
+  resultsImageAlt: "search.results.image_alt",
+
+  // ── the query box ────────────────────────────────────────────────────────
+  boxLabel: "search.box.label",
+  boxPlaceholder: "search.box.placeholder",
+  boxSubmit: "search.box.submit",
+  boxClear: "search.box.clear",
+  /** Accessible name of the suggestion list under the box. */
+  boxSuggestions: "search.box.suggestions",
 
   // ── sort ─────────────────────────────────────────────────────────────────
   sortLabel: "search.sort.label",
@@ -64,6 +74,13 @@ export const SEARCH_I18N_KEYS = {
   sortDistance: "search.sort.distance",
   sortServerChose: "search.sort.server_chose",
 
+  // ── how the results are ARRANGED (see ViewSwitch) ────────────────────────
+  /** The switch's own accessible name — a `Segmented` renders a radiogroup
+   * with no `<label for>` to name it. */
+  viewLabel: "search.view.label",
+  viewList: "search.view.list",
+  viewGrid: "search.view.grid",
+
   // ── facets ───────────────────────────────────────────────────────────────
   facetsTitle: "search.facets.title",
   facetsLoading: "search.facets.loading",
@@ -79,10 +96,60 @@ export const SEARCH_I18N_KEYS = {
   facetsRangeFrom: "search.facets.range_from",
   facetsRangeTo: "search.facets.range_to",
   facetsRangeApply: "search.facets.range_apply",
+  facetsRangeClear: "search.facets.range_clear",
+  /** Accessible names: the visible "From"/"To" repeat on every row, so the
+   * field's own name has to carry the feature it belongs to. */
+  facetsRangeFromAria: "search.facets.range_from_aria",
+  facetsRangeToAria: "search.facets.range_to_aria",
+  /** The reason "Apply" is off: the range reads backwards. */
+  facetsRangeInvalid: "search.facets.range_invalid",
+  /** The fold on a long facet group: "Show all (46)". The number is in
+   * brackets and not a counted noun, so this is one message and not a plural
+   * family — "(1)" never renders, because a group is only folded when the
+   * tail is longer than one row. */
+  facetsShowAll: "search.facets.show_all",
+  facetsShowLess: "search.facets.show_less",
+
+  // ── the filter panel as a whole (phone sheet + host slots) ───────────────
+  filtersOpen: "search.filters.open",
+  /** The sheet's commit button when the count is unknown. */
+  filtersApply: "search.filters.apply",
+  /** "Show N results" — an EXACT count on the sheet's commit button.
+   * A PLURAL FAMILY. */
+  filtersShowCount: "search.filters.show_count",
+  /** "Show N+ results" — a FLOOR on the same button. A PLURAL FAMILY. */
+  filtersShowCountAtLeast: "search.filters.show_count_at_least",
+  filtersDismiss: "search.filters.dismiss",
+  /** The accessible name of the phone chip ROW — a `role="group"` holding a
+   * dozen buttons is announced as nothing at all without one. */
+  filtersChipsLabel: "search.filters.chips_label",
+  /** 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",
+  /** 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",
+
+  // ── category (a host slot, plus the control that removes it) ─────────────
+  categoryTitle: "search.category.title",
+  categoryClear: "search.category.clear",
+  categoryCurrent: "search.category.current",
+
+  // ── language of the query ────────────────────────────────────────────────
+  languageLabel: "search.language.label",
+  languageAny: "search.language.any",
+
+  // ── page size ────────────────────────────────────────────────────────────
+  limitLabel: "search.limit.label",
+  limitOption: "search.limit.option",
+  /** Said beside the control when the URL carries a size the ladder does not
+   * offer — otherwise the story of "we kept your link's size" is invisible. */
+  limitFromLink: "search.limit.from_link",
 
   // ── geo ──────────────────────────────────────────────────────────────────
   geoTitle: "search.geo.title",
   geoRadiusKm: "search.geo.radius_km",
+  geoRadiusLabel: "search.geo.radius_label",
   geoClear: "search.geo.clear",
   geoBox: "search.geo.box",
   geoCenter: "search.geo.center",
@@ -140,6 +207,8 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.resultsCountApproximate,
   SEARCH_I18N_KEYS.resultsCountAtLeast,
   SEARCH_I18N_KEYS.resultsCountExact,
+  SEARCH_I18N_KEYS.filtersShowCount,
+  SEARCH_I18N_KEYS.filtersShowCountAtLeast,
 ];
 
 /**
@@ -176,6 +245,13 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.results.distance_km": "{km} km away",
   "search.results.untitled": "Untitled",
   "search.results.open": "Open",
+  "search.results.image_alt": "Photo of {title}",
+
+  "search.box.label": "Search",
+  "search.box.placeholder": "What are you looking for?",
+  "search.box.submit": "Search",
+  "search.box.clear": "Clear the search",
+  "search.box.suggestions": "Suggestions",
 
   "search.sort.label": "Sort",
   "search.sort.relevance": "Most relevant",
@@ -185,6 +261,10 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.sort.distance": "Nearest first",
   "search.sort.server_chose": "Sorted by {sort}",
 
+  "search.view.label": "View",
+  "search.view.list": "List",
+  "search.view.grid": "Grid",
+
   "search.facets.title": "Filters",
   "search.facets.loading": "Loading filters…",
   "search.facets.load_failed": "We could not load the filters",
@@ -201,21 +281,51 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.range_from": "From",
   "search.facets.range_to": "To",
   "search.facets.range_apply": "Apply",
+  "search.facets.range_clear": "Clear",
+  "search.facets.range_from_aria": "{feature}, from",
+  "search.facets.range_to_aria": "{feature}, up to",
+  "search.facets.show_all": "Show all ({count})",
+  "search.facets.show_less": "Show fewer",
+  "search.facets.range_invalid":
+    "“From” is larger than “to”, so nothing could match. Swap them to apply this range.",
+
+  "search.filters.open": "Filters ({count})",
+  "search.filters.apply": "Show results",
+  "search.filters.show_count.one": "Show {count} result",
+  "search.filters.show_count.other": "Show {count} results",
+  "search.filters.show_count_at_least.one": "Show {count}+ result",
+  "search.filters.show_count_at_least.other": "Show {count}+ results",
+  "search.filters.dismiss": "Close the filters",
+  "search.filters.chips_label": "Filters",
+  "search.filters.all": "All filters",
+  "search.filters.chip_more": ", +{count}",
+
+  "search.category.title": "Category",
+  "search.category.clear": "Search the whole catalogue",
+  "search.category.current": "Searching inside {path}",
+
+  "search.language.label": "Query language",
+  "search.language.any": "Any language",
+
+  "search.limit.label": "Per page",
+  "search.limit.option": "{count} per page",
+  "search.limit.from_link": "This link sets its own page size.",
 
   "search.geo.title": "Location",
   "search.geo.radius_km": "Within {km} km",
+  "search.geo.radius_label": "Radius, km",
   "search.geo.clear": "Anywhere",
   "search.geo.box": "Inside the shown area",
   "search.geo.center": "Around {lat}, {lon}",
 
   "search.url.issues_title": "Part of this link could not be read",
-  "search.url.issue.not_a_number": "{param} is not a number and was ignored",
+  "search.url.issue.not_a_number": "“{param}” in this link is not a number, so it was ignored",
   "search.url.issue.geo_incomplete":
-    "the location needs both lat and lon, so it was ignored",
+    "the location in this link is only half there, so it was ignored",
   "search.url.issue.bbox_malformed":
-    "the area needs four numbers (minLat,minLon,maxLat,maxLon) and was ignored",
+    "the map area in this link is incomplete, so it was ignored",
   "search.url.issue.range_malformed":
-    "{param} is not a from..to range and was ignored",
+    "the range “{param}” in this link needs two numbers, so it was ignored",
 
   "search.degraded.title": "What this search could not do",
   "search.degraded.typo_tolerance":

package/src/i18n/ru.ts

@@ -62,6 +62,13 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.results.distance_km": "{km} км от вас",
   "search.results.untitled": "Без названия",
   "search.results.open": "Открыть",
+  "search.results.image_alt": "Фото: {title}",
+
+  "search.box.label": "Поиск",
+  "search.box.placeholder": "Что ищете?",
+  "search.box.submit": "Найти",
+  "search.box.clear": "Очистить запрос",
+  "search.box.suggestions": "Подсказки",
 
   "search.sort.label": "Сортировка",
   "search.sort.relevance": "По релевантности",
@@ -71,6 +78,10 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.sort.distance": "Сначала ближние",
   "search.sort.server_chose": "Отсортировано: {sort}",
 
+  "search.view.label": "Вид",
+  "search.view.list": "Списком",
+  "search.view.grid": "Плиткой",
+
   "search.facets.title": "Фильтры",
   "search.facets.loading": "Загружаем фильтры…",
   "search.facets.load_failed": "Не удалось загрузить фильтры.",
@@ -87,21 +98,56 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.range_from": "От",
   "search.facets.range_to": "До",
   "search.facets.range_apply": "Применить",
+  "search.facets.range_clear": "Сбросить",
+  "search.facets.range_from_aria": "{feature}, от",
+  "search.facets.range_to_aria": "{feature}, до",
+  "search.facets.show_all": "Показать все ({count})",
+  "search.facets.show_less": "Свернуть",
+  "search.facets.range_invalid":
+    "«От» больше, чем «до», — под такой диапазон ничего не подойдёт. Поменяйте значения местами.",
+
+  "search.filters.open": "Фильтры ({count})",
+  "search.filters.apply": "Показать результаты",
+  "search.filters.show_count.one": "Показать {count} объявление",
+  "search.filters.show_count.few": "Показать {count} объявления",
+  "search.filters.show_count.many": "Показать {count} объявлений",
+  "search.filters.show_count.other": "Показать {count} объявления",
+  "search.filters.show_count_at_least.one": "Показать {count}+ объявление",
+  "search.filters.show_count_at_least.few": "Показать {count}+ объявления",
+  "search.filters.show_count_at_least.many": "Показать {count}+ объявлений",
+  "search.filters.show_count_at_least.other": "Показать {count}+ объявления",
+  "search.filters.dismiss": "Закрыть фильтры",
+  "search.filters.chips_label": "Фильтры",
+  "search.filters.all": "Все фильтры",
+  "search.filters.chip_more": ", +{count}",
+
+  "search.category.title": "Категория",
+  "search.category.clear": "Искать по всему каталогу",
+  "search.category.current": "Ищем внутри {path}",
+
+  "search.language.label": "Язык запроса",
+  "search.language.any": "Любой язык",
+
+  "search.limit.label": "На странице",
+  "search.limit.option": "{count} на странице",
+  "search.limit.from_link": "Размер страницы задан этой ссылкой.",
 
   "search.geo.title": "Где искать",
   "search.geo.radius_km": "В радиусе {km} км",
+  "search.geo.radius_label": "Радиус, км",
   "search.geo.clear": "Везде",
   "search.geo.box": "В показанной области",
   "search.geo.center": "Рядом с {lat}, {lon}",
 
   "search.url.issues_title": "Часть этой ссылки прочитать не удалось",
-  "search.url.issue.not_a_number": "{param} — не число, параметр пропущен",
+  "search.url.issue.not_a_number":
+    "«{param}» в этой ссылке — не число, поэтому параметр пропущен",
   "search.url.issue.geo_incomplete":
-    "для точки нужны и lat, и lon — параметр пропущен",
+    "точка в этой ссылке указана наполовину, поэтому она пропущена",
   "search.url.issue.bbox_malformed":
-    "для области нужны четыре числа (minLat,minLon,maxLat,maxLon) — параметр пропущен",
+    "область на карте в этой ссылке указана не полностью, поэтому она пропущена",
   "search.url.issue.range_malformed":
-    "{param} — не диапазон вида from..to, параметр пропущен",
+    "диапазону «{param}» в этой ссылке не хватает чисел, поэтому он пропущен",
 
   "search.degraded.title": "Что этот поиск не смог сделать",
   "search.degraded.typo_tolerance":

package/src/index.ts

@@ -102,6 +102,24 @@ export type {
   FacetOption,
 } from "./state/facets.js";
 
+export {
+  RANGE_FEATURE_TYPES,
+  buildRangeGroups,
+  isRangeFeature,
+  isRangeUsable,
+} from "./state/ranges.js";
+export type { BuildRangeGroupsInput, RangeGroup } from "./state/ranges.js";
+
+export {
+  SEARCH_BOX_DEBOUNCE_MS,
+  SEARCH_BOX_SUGGEST_DEBOUNCE_MS,
+  SEARCH_DEFAULT_PAGE_SIZE,
+  SEARCH_MAX_PAGE_SIZE,
+  SEARCH_QUERY_MAX_CHARS,
+  SUGGEST_MAX_LIMIT,
+  SUGGEST_MIN_CHARS,
+} from "./state/limits.js";
+
 // ── model (runtime wiring, query keys, context, hooks) ───────────────────────
 export { createSearchRuntime } from "./model/runtime.js";
 export type {
@@ -117,7 +135,7 @@ export {
 export { searchQueryKeys } from "./model/queryKeys.js";
 export type { SearchQueryKeyParams } from "./model/queryKeys.js";
 
-export { useRankingDisclosure, useSearchQuery } from "./model/queries.js";
+export { useRankingDisclosure, useSearchQuery, useSuggest } from "./model/queries.js";
 
 // ── headless (renderless components) ─────────────────────────────────────────
 export { SearchProvider } from "./headless/SearchProvider.js";
@@ -129,9 +147,11 @@ export type {
 } from "./headless/SearchStateProvider.js";
 export { SearchResults } from "./headless/SearchResults.js";
 export type { SearchPageInfo, SearchResultsBag } from "./headless/SearchResults.js";
-export { FacetPanel } from "./headless/FacetPanel.js";
+export { FacetPanel, useFacetPanel } from "./headless/FacetPanel.js";
 export type { FacetPanelBag } from "./headless/FacetPanel.js";
 export { useAppliedSort } from "./headless/useAppliedSort.js";
+export { useSearchBox } from "./headless/useSearchBox.js";
+export type { SearchBoxBag, UseSearchBoxOptions } from "./headless/useSearchBox.js";
 export { RankingDisclosure } from "./headless/RankingDisclosure.js";
 export type { RankingDisclosureBag } from "./headless/RankingDisclosure.js";
 

package/src/model/queries.ts

@@ -6,7 +6,9 @@ import type {
   RankingResponse,
   SearchQueryState,
   SearchResponse,
+  SuggestResponse,
 } from "../api/types.js";
+import { SUGGEST_MAX_LIMIT, SUGGEST_MIN_CHARS } from "../state/limits.js";
 import { useSearchApi } from "./context.js";
 import { searchQueryKeys } from "./queryKeys.js";
 
@@ -60,6 +62,52 @@ export function useSearchQuery(
   });
 }
 
+/**
+ * Title prefixes from the index, for the search box's typeahead.
+ *
+ * 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.
+ *
+ * `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
+ * prefix too short to mean anything. `placeholderData: keepPreviousData` keeps
+ * the previous list under the cursor while the next one is in flight — a menu
+ * that empties and refills on every keystroke is a menu nobody can click.
+ *
+ * `staleTime` is a minute: the index changes when something is published, not
+ * between two letters of one word.
+ */
+export function useSuggest(params: {
+  readonly type: string;
+  readonly q: string;
+  readonly limit?: number;
+  readonly enabled?: boolean;
+}): UseQueryResult<SuggestResponse, StapelApiError> {
+  const api = useSearchApi();
+  const q = params.q.trim();
+  const limit = params.limit;
+  return useQuery({
+    queryKey: searchQueryKeys.suggest(params.type, q, limit),
+    queryFn: ({ signal }) =>
+      api.suggest(
+        {
+          type: params.type,
+          q,
+          ...(limit !== undefined ? { limit: Math.min(limit, SUGGEST_MAX_LIMIT) } : {}),
+        },
+        { signal }
+      ),
+    enabled:
+      (params.enabled ?? true) &&
+      params.type.length > 0 &&
+      q.length >= SUGGEST_MIN_CHARS,
+    placeholderData: keepPreviousData,
+    staleTime: 60_000,
+    retry: false,
+  });
+}
+
 /**
  * The P2B Art. 5 ranking disclosure.
  *
@@ -67,12 +115,14 @@ export function useSearchQuery(
  * not while a person reads the page it explains.
  */
 export function useRankingDisclosure(
-  type?: string
+  type?: string,
+  options?: { readonly enabled?: boolean }
 ): UseQueryResult<RankingResponse, StapelApiError> {
   const api = useSearchApi();
   return useQuery({
     queryKey: searchQueryKeys.ranking(type),
     queryFn: ({ signal }) => api.ranking(type, { signal }),
+    enabled: options?.enabled ?? true,
     staleTime: Number.POSITIVE_INFINITY,
     retry: false,
   });