@stapel/search-react 0.19.0 → 0.21.0

package/src/headless/SearchStateProvider.tsx

@@ -2,9 +2,7 @@ import {
   createContext,
   useCallback,
   useContext,
-  useEffect,
   useMemo,
-  useRef,
 } from "react";
 import type { ReactElement, ReactNode } from "react";
 import type {
@@ -57,8 +55,37 @@ export interface SearchStateBag {
   readonly state: SearchQueryState;
   /** What the URL carried that could not be read (see `SearchStateIssue`). */
   readonly issues: readonly SearchStateIssue[];
-  /** Facet values + ranges + geo the person has applied. */
+  /** Facet values + ranges + geo the person has applied.
+   *
+   * Everything counted here was chosen BY the person: this pair applies no
+   * filter of its own, so the number beside "clear all" can never be one the
+   * reader has to go hunting for.
+   */
   readonly activeFilters: number;
+  /**
+   * A location the host can narrow to, which nobody has accepted yet —
+   * `undefined` when the host offers none, or when the search already carries
+   * a location of its own (an offer would then be a second answer to a
+   * question already answered).
+   *
+   * Draw it as an invitation ("near me"), never as state.
+   */
+  readonly geoOffer: SearchGeo | undefined;
+  /**
+   * Whether the location this search is USING is the one the host offered —
+   * i.e. the visitor pressed "near me" (or followed a link built by somebody
+   * who did) and has not moved the pin since.
+   *
+   * A fact about provenance, and only the provider holds it: `state.geo` is a
+   * centre and a radius, and every way of arriving at a centre produces the
+   * same three numbers. Without it a summary line has to guess, and the guess
+   * it shipped was "a chosen place on the map" — said to a person who had
+   * pressed a button and never opened a map.
+   *
+   * `false` whenever there is no offer to compare against, which includes
+   * every search on a host that offers none.
+   */
+  readonly geoIsOffer: boolean;
 
   setText(q: string): void;
   setSort(sort: string | null): void;
@@ -72,50 +99,71 @@ export interface SearchStateBag {
   clearAll(): void;
   /** Move to a keyset page. The ONLY mutator that keeps a cursor. */
   goToAnchor(anchor: string | null, direction: "next" | "prev"): void;
+  /** Accept {@link geoOffer}. A no-op when there is nothing on offer, so a
+   * control can be pressed without first re-checking what this bag says. */
+  acceptGeoOffer(): void;
   /** Escape hatch for a host control this pair does not ship. Goes through
    * `patchSearchState`, so it drops the cursor like every other change. */
   patch(patch: SearchStatePatch): void;
 }
 
+/**
+ * How close two coordinates have to be to be the same place, in degrees.
+ *
+ * The applied location makes a round trip through the query string, so the
+ * numbers that come back are the ones `String(lat)` produced rather than the
+ * float the device handed over. 1e-6 degrees is ~11cm — far below any
+ * position a browser reports and far above any rounding the codec introduces.
+ */
+const SAME_PLACE_EPSILON = 1e-6;
+
+/** Is the applied location the offered one? See {@link SearchStateBag.geoIsOffer}. */
+function sameCenter(
+  applied: SearchGeo | undefined,
+  offered: SearchGeo | undefined
+): boolean {
+  if (applied === undefined || offered === undefined) return false;
+  if (applied.kind !== "center" || offered.kind !== "center") return false;
+  return (
+    Math.abs(applied.lat - offered.lat) < SAME_PLACE_EPSILON &&
+    Math.abs(applied.lon - offered.lon) < SAME_PLACE_EPSILON
+  );
+}
+
 const StateContext = createContext<SearchStateBag | null>(null);
 
 export interface SearchStateProviderProps extends ParseSearchStateOptions {
   readonly adapter: SearchParamsAdapter;
   /**
-   * Where to centre the results when the URL says nothing about location —
-   * the visitor's own position, as the HOST resolved it (a granted browser
-   * geolocation prompt, or the server's IP guess when there was none).
+   * A location this search COULD be narrowed to — offered, never applied.
    *
-   * Opt-in, and it is deliberately not one of the `default*` parse options
-   * beside it. Those are read-time fallbacks: `defaultCategory` fills a gap in
-   * the parsed state and never reaches the query string. A location cannot
-   * work that way. It has to be WRITTEN, once, because the URL is the state:
-   * a centre that lived only in the parse would vanish from a link the visitor
-   * shares, and — worse — would be re-applied on the very next render after
-   * they cleared it, which is a filter that will not come off.
+   * The host resolves it (a granted browser prompt, the server's IP guess);
+   * this provider does nothing with it except hand it back on the bag as
+   * {@link SearchStateBag.geoOffer}, so a control can draw "near me" and the
+   * PERSON decides. Nothing is written to the URL until they press it.
    *
-   * So the rules, all four of which are about not overruling a person:
+   * ## Why this is an offer and not a default (defect: a silent radius)
    *
-   *  - **Only into an empty URL.** A link that carries `lat`/`lon` or `bbox`
-   *    already means a place, and it must mean the same place for everybody
-   *    who opens it. A default that overwrote it would make one address bar
-   *    two different searches.
-   *  - **Once.** Tracked as "has anyone spoken about location yet", in a ref —
-   *    not by comparing the default against the current value, which cannot
-   *    tell "the visitor cleared it" from "it has not been applied".
-   *  - **Never after a clear.** `setGeo` marks the question answered, so a
-   *    person who widens the search back to everywhere stays there.
-   *  - **Late is fine.** A browser prompt and an IP round trip both resolve
-   *    after the first paint, so `undefined` now and a value three renders
-   *    later still applies — provided the URL is still empty of geo at that
-   *    moment.
+   * The previous shape of this prop (`defaultGeo`) wrote the visitor's
+   * position into the query string on the first render that could, under four
+   * careful rules about not overruling a person. Every rule held, and the
+   * result was still a filter nobody asked for: a browser permission granted
+   * once, for one map, became a permanent 25 km wall around every category
+   * leaf and every result page in the deployment. Measured on a live board:
+   * 48 phones became 17, and three leaves with stock became "nothing found".
+   * The page looks perfectly healthy while doing it, which is what makes it
+   * dangerous — the honest reading of an empty leaf is "this board is empty",
+   * not "your browser told us where you are".
    *
-   * It REPLACES the history entry rather than pushing one: the visitor did not
-   * perform this change, and Back should leave the page, not undo a centring
-   * they never asked for. The adapter's `setParams` takes `{ replace: true }`
-   * for exactly this, and the react-router binding honours it.
+   * There is no set of rules that fixes that, because the defect is not in
+   * the rules: applying a spatial filter is a decision about what the person
+   * wants to see, and only they hold it. So the prop carries the same value
+   * and the provider no longer commits it. Two more defects fall out with it:
+   * the URL is never rewritten behind the visitor (a hand-typed `radius_km`
+   * survives), and the results are fetched ONCE instead of being fetched and
+   * immediately superseded by a second, narrower query.
    */
-  readonly defaultGeo?: SearchGeo | undefined;
+  readonly geoOffer?: SearchGeo | undefined;
   readonly children: ReactNode;
 }
 
@@ -128,7 +176,7 @@ export interface SearchStateProviderProps extends ParseSearchStateOptions {
 export function SearchStateProvider(
   props: SearchStateProviderProps
 ): ReactElement {
-  const { adapter, children, defaultGeo, ...parseOptions } = props;
+  const { adapter, children, geoOffer, ...parseOptions } = props;
   const { params, setParams } = adapter;
 
   // The parse options are spread into a stable dependency: a host that builds
@@ -165,19 +213,26 @@ export function SearchStateProvider(
     [setParams, search]
   );
 
-  /**
-   * Has anything at all said where to search yet?
-   *
-   * `true` once the URL was seen carrying a location, once `defaultGeo` has
-   * been applied, or once anybody called `setGeo` — including with `null`.
-   * That last one is the whole reason this is a ref and not a comparison: a
-   * cleared location and an unapplied default look identical in the state, and
-   * only the record of who spoke tells them apart.
-   */
-  const geoSettled = useRef(false);
 
   const bag = useMemo<SearchStateBag>(() => {
     const state = parsed.state;
+    /**
+     * The offer, carrying the radius the URL already asked for.
+     *
+     * `?radius_km=300` with no `lat`/`lon` narrows nothing — there is no
+     * point to measure from — but it IS a number the person typed, and the
+     * offer used to ignore it twice over: the button advertised the host's
+     * own 25km, and pressing it wrote 25 into the address over the 300 that
+     * was already there. Three things now agree, which is the whole of the
+     * fix: what the link asked for, what the button says, and what pressing
+     * it does. A bbox offer is left alone — a box has no radius to carry.
+     */
+    const offer: SearchGeo | undefined =
+      geoOffer !== undefined &&
+      geoOffer.kind === "center" &&
+      parsed.orphanRadiusKm !== undefined
+        ? { ...geoOffer, radiusKm: parsed.orphanRadiusKm }
+        : geoOffer;
     const apply = (
       next: SearchQueryState,
       options?: { readonly replace?: boolean }
@@ -188,6 +243,13 @@ export function SearchStateProvider(
       state,
       issues: parsed.issues,
       activeFilters: activeFilterCount(state),
+      // An offer stands only while the question is open. Once the search
+      // carries a place — from a link, or because somebody pressed the offer
+      // — there is nothing left to offer, and a control that kept drawing
+      // "near me" beside an applied location would be inviting a person to
+      // re-answer a question they can already see the answer to.
+      geoOffer: state.geo === undefined ? offer : undefined,
+      geoIsOffer: sameCenter(state.geo, offer),
 
       // Typing replaces rather than pushes: one history entry per letter
       // would make Back useless, which is the control the spec's acceptance
@@ -200,12 +262,14 @@ export function SearchStateProvider(
       setFilter: (slug, values) => apply(setFilterValues(state, slug, values)),
       setRange: (slug, range) => apply(setRangeValue(state, slug, range)),
       setGeo: (geo) => {
-        // The person has now answered the location question themselves —
-        // including by answering "anywhere". `defaultGeo` does not get to ask
-        // it again.
-        geoSettled.current = true;
         apply(patchSearchState(state, { geo }));
       },
+      acceptGeoOffer: () => {
+        if (offer === undefined || state.geo !== undefined) return;
+        // A PUSH, like any other filter the person applies: Back takes the
+        // narrowing off again, which is the same promise every chip makes.
+        apply(patchSearchState(state, { geo: offer }));
+      },
       // A page size is a preference, not a step through the results.
       setLimit: (limit) => apply(patchSearchState(state, { limit }), { replace: true }),
       clearAll: () => apply(clearFilters(state)),
@@ -213,25 +277,8 @@ export function SearchStateProvider(
         apply(patchSearchState(state, { anchor, direction })),
       patch: (patch) => apply(patchSearchState(state, patch)),
     };
-  }, [parsed, commit]);
-
-  // An effect, not a render-time write: this puts a value in the URL, and a
-  // router asked to navigate during a render is a warning at best and a loop
-  // at worst. It runs after every commit, which is what makes a `defaultGeo`
-  // that arrives on the fourth render — the browser prompt finally answered —
-  // land as reliably as one present on the first.
-  useEffect(() => {
-    if (geoSettled.current) return;
-    if (parsed.state.geo !== undefined) {
-      // The link brought its own place. That settles the question for this
-      // visit even if the host is still resolving one of its own.
-      geoSettled.current = true;
-      return;
-    }
-    if (defaultGeo === undefined) return;
-    geoSettled.current = true;
-    commit(patchSearchState(parsed.state, { geo: defaultGeo }), { replace: true });
-  }, [defaultGeo, parsed.state, commit]);
+  }, [parsed, commit, geoOffer]);
+
 
   return <StateContext.Provider value={bag}>{children}</StateContext.Provider>;
 }

package/src/i18n/es.ts

@@ -75,6 +75,10 @@ export const searchI18nBundleEs: I18nDictionary = {
     "Los recuentos son aproximados: había demasiados candidatos para contarlos todos.",
   "search.facets.skipped":
     "Estos filtros no se contaron para esta búsqueda: {slugs}",
+  "search.facets.withheld.one":
+    "{count} filtro se aplica a muy pocos de estos resultados",
+  "search.facets.withheld.other":
+    "{count} filtros se aplican a muy pocos de estos resultados",
   "search.facets.not_counted": "sin contar",
   "search.facets.drill_down_hint":
     "Cada recuento es lo que obtendrías eligiendo ese valor en lugar del actual.",
@@ -125,11 +129,14 @@ export const searchI18nBundleEs: I18nDictionary = {
 
   "search.geo.title": "Ubicación",
   "search.geo.radius_km": "A menos de {km} km",
+  "search.geo.radius_km_short": "{km} km",
   "search.geo.radius_label": "Radio, km",
   "search.geo.clear": "En cualquier lugar",
+  "search.geo.near_me": "Cerca de mí",
   "search.geo.everywhere": "Buscando en todas partes",
   "search.geo.box": "Dentro del área mostrada",
   "search.geo.chosen_place": "Un lugar elegido en el mapa",
+  "search.geo.near_you": "Cerca de ti",
 
   "search.url.issues_title": "Parte de este enlace no se pudo leer",
   "search.url.issue.not_a_number":
@@ -140,6 +147,8 @@ export const searchI18nBundleEs: I18nDictionary = {
     "el área del mapa de este enlace está incompleta, así que se ignoró",
   "search.url.issue.range_malformed":
     "al rango «{param}» de este enlace le faltan números, así que se ignoró",
+  "search.url.issue.radius_without_place":
+    "este enlace pide un radio pero no nombra ningún lugar, así que aún no se acota nada — elige un lugar y se aplicará ese mismo radio",
 
   "search.degraded.title": "Lo que esta búsqueda no pudo hacer",
   "search.degraded.typo_tolerance":
@@ -150,6 +159,8 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.degraded.exact_facet_counts": "Los recuentos de filtros son aproximados.",
   "search.degraded.category_rollup":
     "Pueden faltar subcategorías en estos resultados: el servicio de categorías no respondió.",
+  "search.degraded.facet_plan_evidence":
+    "No pudimos determinar qué filtros encajan con estos resultados, así que puede haber más de los que muestra el panel.",
   "search.degraded.scorer":
     "El parámetro de ranking «{scorer}» no se aplicó: el motor configurado no puede evaluarlo.",
   "search.degraded.unknown":

package/src/i18n/keys.ts

@@ -116,6 +116,17 @@ export const SEARCH_I18N_KEYS = {
   facetsClearAll: "search.facets.clear_all",
   facetsApproximate: "search.facets.approximate",
   facetsSkipped: "search.facets.skipped",
+  /**
+   * "N filters apply to too few of these results" — the sentence that
+   * REPLACES {@link facetsEmpty} whenever `facet_meta.withheld` is not
+   * empty. A PLURAL FAMILY: it counts a noun in words.
+   *
+   * D175: a branch category holding 46 phones that all carry a manufacturer
+   * printed "this search offers no filters". The groups were counted and
+   * then withheld for covering too little of the set — so "there are none"
+   * was false, and the honest sentence is this one, with the number in it.
+   */
+  facetsWithheld: "search.facets.withheld",
   /** Shown INSTEAD of a count for a slug the server did not count. */
   facetsNotCounted: "search.facets.not_counted",
   facetsDrillDownHint: "search.facets.drill_down_hint",
@@ -217,8 +228,22 @@ export const SEARCH_I18N_KEYS = {
   // ── geo ──────────────────────────────────────────────────────────────────
   geoTitle: "search.geo.title",
   geoRadiusKm: "search.geo.radius_km",
+  /**
+   * The same number, said in the fewest words that still say it — for the
+   * OFFER, where the sentence shares a 390px line with a place name and the
+   * word "Filters".
+   *
+   * Measured at 390: "Near me · Within 25 km" made the control 272px wide
+   * against 231px of room, so the offer was cut mid-word by the group's own
+   * clip and the filters door overlapped it by 52px. Dropping the number
+   * instead was not an option — a button that says only "near me" asks a
+   * person to accept a radius they cannot see, which is the whole reason the
+   * offer states one. So the PREPOSITION goes and the number stays.
+   */
+  geoRadiusKmShort: "search.geo.radius_km_short",
   geoRadiusLabel: "search.geo.radius_label",
   geoClear: "search.geo.clear",
+  geoNearMe: "search.geo.near_me",
   /**
    * What `<LocationSummaryLine>` says when NO location is applied.
    *
@@ -242,6 +267,18 @@ export const SEARCH_I18N_KEYS = {
    * `geoLabel` and this sentence never appears.
    */
   geoChosenPlace: "search.geo.chosen_place",
+  /**
+   * What the line says when the applied location IS the position the host
+   * offered — the visitor pressed "Near me" and nothing else has moved since.
+   *
+   * Measured on a live leaf: pressing the offer turned the line into "A chosen
+   * place on the map", to a person who had never opened a map. The sentence
+   * was not wrong about the mechanism (a centre with a radius is what a map
+   * pick produces); it was wrong about the only thing the reader can check —
+   * how the search came to be looking there. The provider reports the fact
+   * (`geoIsOffer`) rather than this file guessing at it.
+   */
+  geoNearYou: "search.geo.near_you",
 
   // ── the URL that could not be read ───────────────────────────────────────
   urlIssuesTitle: "search.url.issues_title",
@@ -249,6 +286,8 @@ export const SEARCH_I18N_KEYS = {
   urlIssueGeoIncomplete: "search.url.issue.geo_incomplete",
   urlIssueBboxMalformed: "search.url.issue.bbox_malformed",
   urlIssueRangeMalformed: "search.url.issue.range_malformed",
+  /** A radius with no point to measure it from — see `urlState.ts`. */
+  urlIssueRadiusWithoutPlace: "search.url.issue.radius_without_place",
 
   // ── degradations (the envelope's `degraded[]`) ───────────────────────────
   degradedTitle: "search.degraded.title",
@@ -257,6 +296,10 @@ export const SEARCH_I18N_KEYS = {
   degradedExactTotal: "search.degraded.exact_total",
   degradedExactFacetCounts: "search.degraded.exact_facet_counts",
   degradedCategoryRollup: "search.degraded.category_rollup",
+  /** The engine cannot say which categories the results are in, so no facet
+   * plan could be drawn from them — a READER-facing sentence, because the
+   * consequence is a filter panel that is thinner than the catalogue. */
+  degradedFacetPlanEvidence: "search.degraded.facet_plan_evidence",
   degradedScorer: "search.degraded.scorer",
   degradedUnknown: "search.degraded.unknown",
 
@@ -328,6 +371,7 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.filtersShowCountAtLeast,
   SEARCH_I18N_KEYS.boxCategoryCount,
   SEARCH_I18N_KEYS.facetsMatchCount,
+  SEARCH_I18N_KEYS.facetsWithheld,
 ];
 
 /**
@@ -400,6 +444,10 @@ export const searchI18nBundleEn: Record<string, string> = {
     "Counts are approximate — there were too many candidates to count them all.",
   "search.facets.skipped":
     "These filters were not counted for this search: {slugs}",
+  "search.facets.withheld.one":
+    "{count} filter applies to too few of these results",
+  "search.facets.withheld.other":
+    "{count} filters apply to too few of these results",
   "search.facets.not_counted": "not counted",
   "search.facets.drill_down_hint":
     "Each count is what you would get by choosing that value instead of the one you have.",
@@ -449,12 +497,15 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.limit.from_link": "This link sets its own page size.",
 
   "search.geo.title": "Location",
+  "search.geo.near_me": "Near me",
   "search.geo.radius_km": "Within {km} km",
+  "search.geo.radius_km_short": "{km} km",
   "search.geo.radius_label": "Radius, km",
   "search.geo.clear": "Anywhere",
   "search.geo.everywhere": "Searching everywhere",
   "search.geo.box": "Inside the shown area",
   "search.geo.chosen_place": "A chosen place on the map",
+  "search.geo.near_you": "Near you",
 
   "search.url.issues_title": "Part of this link could not be read",
   "search.url.issue.not_a_number": "“{param}” in this link is not a number, so it was ignored",
@@ -464,6 +515,8 @@ export const searchI18nBundleEn: Record<string, string> = {
     "the map area in this link is incomplete, so it was ignored",
   "search.url.issue.range_malformed":
     "the range “{param}” in this link needs two numbers, so it was ignored",
+  "search.url.issue.radius_without_place":
+    "this link asks for a radius but names no place, so nothing is narrowed yet — choose a place and this radius is the one that applies",
 
   "search.degraded.title": "What this search could not do",
   "search.degraded.typo_tolerance":
@@ -474,6 +527,8 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.degraded.exact_facet_counts": "The filter counts are approximate.",
   "search.degraded.category_rollup":
     "Subcategories may be missing from these results — the category service did not answer.",
+  "search.degraded.facet_plan_evidence":
+    "We could not work out which filters fit these results, so there may be more than the panel shows.",
   "search.degraded.scorer":
     "The ranking parameter “{scorer}” was not applied — the search engine in use cannot evaluate it.",
   "search.degraded.unknown":

package/src/i18n/ru.ts

@@ -100,6 +100,14 @@ export const searchI18nBundleRu: I18nDictionary = {
     "Счётчики приблизительные — подходящих объявлений слишком много, чтобы пересчитать все.",
   "search.facets.skipped":
     "Эти фильтры для текущего поиска не посчитаны: {slugs}",
+  "search.facets.withheld.one":
+    "Ещё {count} фильтр подходит слишком малой части результатов",
+  "search.facets.withheld.few":
+    "Ещё {count} фильтра подходят слишком малой части результатов",
+  "search.facets.withheld.many":
+    "Ещё {count} фильтров подходят слишком малой части результатов",
+  "search.facets.withheld.other":
+    "Ещё {count} фильтра подходят слишком малой части результатов",
   "search.facets.not_counted": "не посчитано",
   "search.facets.drill_down_hint":
     "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",
@@ -156,11 +164,14 @@ export const searchI18nBundleRu: I18nDictionary = {
 
   "search.geo.title": "Где искать",
   "search.geo.radius_km": "В радиусе {km} км",
+  "search.geo.radius_km_short": "{km} км",
   "search.geo.radius_label": "Радиус, км",
   "search.geo.clear": "Везде",
+  "search.geo.near_me": "Рядом со мной",
   "search.geo.everywhere": "Ищем везде",
   "search.geo.box": "В показанной области",
   "search.geo.chosen_place": "Выбранное место на карте",
+  "search.geo.near_you": "Рядом с вами",
 
   "search.url.issues_title": "Часть этой ссылки прочитать не удалось",
   "search.url.issue.not_a_number":
@@ -171,6 +182,8 @@ export const searchI18nBundleRu: I18nDictionary = {
     "область на карте в этой ссылке указана не полностью, поэтому она пропущена",
   "search.url.issue.range_malformed":
     "диапазону «{param}» в этой ссылке не хватает чисел, поэтому он пропущен",
+  "search.url.issue.radius_without_place":
+    "в ссылке задан радиус, но не задано место, поэтому пока ничего не сузилось — выберите место, и применится именно этот радиус",
 
   "search.degraded.title": "Что этот поиск не смог сделать",
   "search.degraded.typo_tolerance":
@@ -181,6 +194,8 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.degraded.exact_facet_counts": "Счётчики фильтров приблизительные.",
   "search.degraded.category_rollup":
     "В выдаче могут отсутствовать подкатегории — сервис категорий не ответил.",
+  "search.degraded.facet_plan_evidence":
+    "Не удалось определить, какие фильтры подходят этим результатам, — их может быть больше, чем показано.",
   "search.degraded.scorer":
     "Параметр ранжирования «{scorer}» не применялся — используемый движок не умеет его считать.",
   "search.degraded.unknown":

package/src/index.ts

@@ -51,8 +51,10 @@ export {
   suggestTerms,
 } from "./api/types.js";
 export type {
+  FacetCategoryCount,
   FacetMeta,
   FacetSelection,
+  FacetWithheldGroup,
   RankingResponse,
   Scorer,
   SearchDegradation,
@@ -95,6 +97,7 @@ export type {
 } from "./state/urlState.js";
 
 export {
+  FACET_PLAN_EVIDENCE,
   countIsEstimate,
   countKind,
   degradationAudience,

package/src/state/degradations.ts

@@ -17,12 +17,26 @@ import type { SearchDegradation, SearchDegradationKind } from "../api/types.js";
 
 const SCORER_PREFIX = "scorer:";
 
+/**
+ * "This answer's facet plan could not be drawn from evidence."
+ *
+ * Named rather than inlined because the FACET PANEL reads the raw literal
+ * off the envelope: whether "this search offers no filters" is a true
+ * sentence is a question about THIS answer, not about the banner, and the
+ * panel must not have to parse the whole list to ask it.
+ */
+export const FACET_PLAN_EVIDENCE = "facet_plan_evidence";
+
 const KNOWN: Readonly<Record<string, SearchDegradationKind>> = {
   typo_tolerance: "typo_tolerance",
   phrase_synonyms: "phrase_synonyms",
   exact_total: "exact_total",
   exact_facet_counts: "exact_facet_counts",
   category_rollup: "category_rollup",
+  // Reader-facing by omission from OPERATOR_KINDS below, and deliberately:
+  // it changes what an empty filter panel MEANS, which is the one thing on
+  // the page a buyer can act on (widen, or filter by category instead).
+  [FACET_PLAN_EVIDENCE]: "facet_plan_evidence",
 };
 
 /** i18n key per kind (`search.degraded.*`). */

package/src/state/facets.ts

@@ -362,6 +362,9 @@ export function facetOptionLabel(
  * a chip in the row. The APPLIED-filter clause outranks the type rule: a
  * constraint the URL carries always gets its control back, whatever the schema
  * now says about it, or a person is left holding a filter they cannot clear.
+ *
+ * A COUNTED group with zero coverage goes the same way, and for the same
+ * reason — see {@link keepsAnAxisOpen}.
  */
 export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGroup[] {
   const bySlug = new Map<string, FeatureDef>();
@@ -462,5 +465,48 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
         selected: selected.includes(value),
       })),
     };
-  });
+  }).filter(keepsAnAxisOpen);
+}
+
+/**
+ * Is this group an axis a person can actually move along?
+ *
+ * The coverage floor stops at the queried category's own schema, on the
+ * server, on purpose: `FACET_MIN_COVERAGE` governs only the slugs an
+ * evidence plan BORROWED from sibling leaves, because "a closed option set
+ * answering with its zeros is a shipped decision". That is right about an
+ * option and wrong about a GROUP. A size chart showing `XL — 0` beside
+ * `M — 12` is telling the truth about a shape the reader wants to see whole;
+ * a group whose every option is 0 is not a shape, it is three checkboxes that
+ * are each guaranteed to return nothing, and it costs a heading in the rail
+ * and a chip on a 390px row to say so.
+ *
+ * Measured on the deployed phones leaf: `sim_config`, `device_history` and
+ * `set` are authored `select` features that no listing in the leaf fills.
+ * The server's `fill_zero_options` creates the slug and zero-fills every
+ * authored option, so all three arrive counted, complete and dead, and the
+ * withholding loop never looks at them because an authored plan has no
+ * `evidence`. Nothing on the wire marks them: the client has to sum the
+ * buckets itself, which is exactly what {@link facetCoverage} already does
+ * for two other surfaces.
+ *
+ * Three things this must NOT drop, which is why the predicate is this narrow:
+ *
+ *  - an UNCOUNTED group (`counted: false`). Its options carry `count: null`,
+ *    so it sums to zero for the opposite reason — nobody looked. "We did not
+ *    count this" and "there are none" are different sentences, and dropping
+ *    on the first is the regression the `MAX_FACET_FIELDS` branch below
+ *    exists to prevent (a live cars leaf: 26 facetable features declared, 12
+ *    counted, and `/query` accepts `f.<slug>` for all 26).
+ *  - a group the reader has ALREADY filtered on, whatever its counts say —
+ *    the same clause that outranks the type rule. Withholding that group
+ *    leaves a constraint applied with no control to undo it.
+ *  - a group with any non-zero option. A zero option beside a live one is
+ *    drill-down working as designed: it reports what swapping to that value
+ *    would get you, and the answer being "nothing" is information.
+ */
+function keepsAnAxisOpen(group: FacetGroup): boolean {
+  if (!group.counted) return true;
+  if (group.selected.length > 0) return true;
+  return facetCoverage(group) > 0;
 }