@stapel/search-react 0.3.1 → 0.7.0

package/src/i18n/es.ts

@@ -22,6 +22,8 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.results.retry": "Reintentar",
   "search.results.count_approximate.one": "Aproximadamente {count} resultado",
   "search.results.count_approximate.other": "Unos {count} resultados",
+  "search.results.count_at_least.one": "{count}+ resultado",
+  "search.results.count_at_least.other": "{count}+ resultados",
   "search.results.count_exact.one": "{count} resultado",
   "search.results.count_exact.other": "{count} resultados",
   "search.results.took_ms": "{ms} ms",
@@ -37,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",
@@ -62,21 +71,47 @@ 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.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.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

@@ -28,9 +28,18 @@ export const SEARCH_I18N_KEYS = {
   resultsLoadFailed: "search.results.load_failed",
   resultsEmpty: "search.results.empty",
   resultsRetry: "search.results.retry",
-  /** "About N results" — the sentence for an ESTIMATED count. A PLURAL
-   * FAMILY: render with `tPlural`, never `t` (see SEARCH_I18N_PLURAL_KEYS). */
+  /**
+   * "About N results" — the sentence for an ESTIMATED count. A PLURAL
+   * FAMILY: render with `tPlural`, never `t` (see SEARCH_I18N_PLURAL_KEYS).
+   *
+   * @deprecated stapel-search 0.2.0 stopped producing estimates: a count is
+   * exact, a FLOOR (`resultsCountAtLeast`), or absent. Kept so a host that
+   * translated it keeps a working key, and no longer rendered by the skin.
+   */
   resultsCountApproximate: "search.results.count_approximate",
+  /** "N+ results" — a LOWER BOUND: at least this many match, possibly more.
+   * A PLURAL FAMILY. Never render a floor as a plain number. */
+  resultsCountAtLeast: "search.results.count_at_least",
   /** "N results" — only when `exact_total` is true. A PLURAL FAMILY. */
   resultsCountExact: "search.results.count_exact",
   resultsTookMs: "search.results.took_ms",
@@ -45,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",
@@ -70,10 +89,45 @@ 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 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",
+
+  // ── 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",
@@ -129,7 +183,10 @@ export type SearchI18nKey =
  */
 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,
 ];
 
 /**
@@ -149,6 +206,8 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.results.retry": "Try again",
   "search.results.count_approximate.one": "About {count} result",
   "search.results.count_approximate.other": "About {count} results",
+  "search.results.count_at_least.one": "{count}+ result",
+  "search.results.count_at_least.other": "{count}+ results",
   "search.results.count_exact.one": "{count} result",
   "search.results.count_exact.other": "{count} results",
   "search.results.took_ms": "{ms} ms",
@@ -164,6 +223,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",
@@ -189,21 +255,46 @@ 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.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.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

@@ -41,6 +41,10 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.results.count_approximate.few": "Примерно {count} объявления",
   "search.results.count_approximate.many": "Примерно {count} объявлений",
   "search.results.count_approximate.other": "Примерно {count} объявления",
+  "search.results.count_at_least.one": "{count}+ объявление",
+  "search.results.count_at_least.few": "{count}+ объявления",
+  "search.results.count_at_least.many": "{count}+ объявлений",
+  "search.results.count_at_least.other": "{count}+ объявления",
   "search.results.count_exact.one": "{count} объявление",
   "search.results.count_exact.few": "{count} объявления",
   "search.results.count_exact.many": "{count} объявлений",
@@ -58,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": "По релевантности",
@@ -83,21 +94,51 @@ 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.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.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

@@ -86,7 +86,14 @@ export type {
   SearchStatePatch,
 } from "./state/urlState.js";
 
-export { countIsEstimate, degradationMessageKey, parseDegradations } from "./state/degradations.js";
+export {
+  countIsEstimate,
+  countKind,
+  degradationMessageKey,
+  isCountNuanceOnly,
+  parseDegradations,
+} from "./state/degradations.js";
+export type { SearchCountKind } from "./state/degradations.js";
 
 export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
 export type {
@@ -95,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 {
@@ -110,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";
@@ -122,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,
   });

package/src/state/degradations.ts

@@ -66,6 +66,11 @@ export function parseDegradations(
  * the envelope's own `exact_total: false`, and the `"exact_total"`
  * degradation. They agree in practice; treating either as decisive is what
  * keeps "≈1 200" from ever being rendered as "1 200".
+ *
+ * @deprecated Since stapel-search 0.2.0 the envelope answers this directly
+ * with `count_is_lower_bound`, and "not exact" now means a FLOOR rather than
+ * a fuzzy number. Use {@link countKind}, which reads the wire field and also
+ * handles `count: null`.
  */
 export function countIsEstimate(
   exactTotal: boolean,
@@ -73,3 +78,58 @@ export function countIsEstimate(
 ): boolean {
   return !exactTotal || degradations.some((d) => d.kind === "exact_total");
 }
+
+/**
+ * How a count may be spoken: as a number, as a floor, or not at all.
+ *
+ * The three states stapel-search 0.2.0 made explicit, because the version
+ * before it had only two and used `0` for both "none match" and "we do not
+ * know" — which is how a storefront came to print "About 0 listings" over
+ * four visible cards.
+ */
+export type SearchCountKind = "exact" | "at_least" | "unknown";
+
+/**
+ * Read the envelope's three count fields as one decision.
+ *
+ * `null` is UNKNOWN and renders as no count line — never as `0`, and never
+ * as "about 0". Anything the server declines to call exact is rendered as a
+ * floor ("N+"), including the defensive case of an `exact_total: false` from
+ * a server that predates `count_is_lower_bound`: claiming "at least N" over
+ * a page that shows N rows is the one reading that cannot be contradicted by
+ * what the reader can see.
+ */
+export function countKind(
+  count: number | null | undefined,
+  isLowerBound: boolean | undefined,
+  exactTotal: boolean,
+  degradations: readonly SearchDegradation[]
+): SearchCountKind {
+  if (count === null || count === undefined) return "unknown";
+  if (isLowerBound === true) return "at_least";
+  return countIsEstimate(exactTotal, degradations) ? "at_least" : "exact";
+}
+
+/**
+ * Is `exact_total` the ONLY thing the engine could not do?
+ *
+ * It is a count NUANCE, not a failed search: the answer is complete, the
+ * rows are the right rows, and the single consequence — that the total is a
+ * floor — is already spoken by the count itself as "N+". Raising a warning
+ * banner over it teaches a reader that a perfectly good result page is
+ * broken, and a banner that cries wolf on every landing page is a banner
+ * nobody reads on the day `category_rollup` shows up in it.
+ *
+ * Every other degradation changes what the page MEANS ("typos were not
+ * corrected", "subcategories may be missing", "counts are approximate") and
+ * still renders. So does `exact_total` when it arrives BESIDE one of them —
+ * the list is then a description of a genuinely degraded answer.
+ */
+export function isCountNuanceOnly(
+  degradations: readonly SearchDegradation[]
+): boolean {
+  return (
+    degradations.length > 0 &&
+    degradations.every((degradation) => degradation.kind === "exact_total")
+  );
+}

package/src/state/limits.ts

@@ -0,0 +1,50 @@
+/**
+ * The backend's own limits, in one place — and the two timings the client
+ * chooses so that it never provokes them.
+ *
+ * Every number here is a fact about stapel-search's `conf.py` (or, for the
+ * debounces, a decision taken because of one). They live in the state layer,
+ * beside the codec, because they are properties of the CONTRACT rather than of
+ * any component: a control that caps its input at `SEARCH_QUERY_MAX_CHARS`
+ * cannot produce `error.400.search_query_too_long`, and a typeahead that waits
+ * for `SEARCH_BOX_SUGGEST_DEBOUNCE_MS` does not earn a 429 from a throttled
+ * endpoint for typing quickly.
+ *
+ * They are DEFAULTS, not assertions: a deployment may raise `MAX_PAGE_SIZE` or
+ * lower `MAX_QUERY_CHARS`, and nothing here is sent to the server as a claim.
+ * The server remains the one entitled to refuse.
+ */
+
+/** `MAX_QUERY_CHARS` — the longest `q` (and suggest prefix) the server reads. */
+export const SEARCH_QUERY_MAX_CHARS = 200;
+
+/** `DEFAULT_PAGE_SIZE` — what a request with no `limit` gets. */
+export const SEARCH_DEFAULT_PAGE_SIZE = 24;
+
+/** `MAX_PAGE_SIZE` — the server clamps anything above this. */
+export const SEARCH_MAX_PAGE_SIZE = 100;
+
+/** `services.suggest` clamps `limit` into `1..25`. */
+export const SUGGEST_MAX_LIMIT = 25;
+
+/**
+ * The shortest prefix worth asking the index about.
+ *
+ * One and two letters match nearly everything, so the answer is noise and the
+ * request is a keystroke tax on a throttled endpoint (`SuggestThrottle`,
+ * scope `search-suggest`). Three is where a prefix starts to mean something.
+ */
+export const SUGGEST_MIN_CHARS = 3;
+
+/** How long the typing has to stop before the SEARCH runs. */
+export const SEARCH_BOX_DEBOUNCE_MS = 350;
+
+/**
+ * How long it has to stop before the INDEX is asked for prefixes.
+ *
+ * Shorter than the commit: a suggestion is only worth having while you are
+ * still typing, and it costs a cheap read of one column. Longer than zero: the
+ * endpoint is throttled per client, and a request per keystroke is how a person
+ * gets 429s for typing quickly.
+ */
+export const SEARCH_BOX_SUGGEST_DEBOUNCE_MS = 150;