@stapel/search-react 0.3.0 → 0.4.0

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",
@@ -129,6 +138,7 @@ export type SearchI18nKey =
  */
 export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.resultsCountApproximate,
+  SEARCH_I18N_KEYS.resultsCountAtLeast,
   SEARCH_I18N_KEYS.resultsCountExact,
 ];
 
@@ -149,6 +159,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",

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} объявлений",

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 {

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")
+  );
+}