@stapel/search-react 0.20.0 → 0.22.0

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",
@@ -146,6 +157,24 @@ export const SEARCH_I18N_KEYS = {
    * Distinct from `facetsEmpty`, which says the SEARCH offers no filters —
    * here the filters exist and the query missed. */
   facetsSearchEmpty: "search.facets.search_empty",
+  /**
+   * The box inside ONE dictionary group — 418 car makes are not a list a
+   * person scrolls. Distinct from `facetsSearch`, which finds a GROUP among
+   * forty headings: one narrows the panel, the other narrows one axis of it,
+   * and a translator handed one string for both has to pick which surface to
+   * be wrong on.
+   */
+  facetsDictionarySearch: "search.facets.dictionary_search",
+  /** The dictionary box matched no value of this group. Not `facetsEmpty`,
+   * and not `facetsSearchEmpty`: the group exists and its values exist. */
+  facetsDictionaryEmpty: "search.facets.dictionary_empty",
+  /** Over the values already chosen, which stay visible whatever the box
+   * says — a filter a person cannot see is a filter they cannot remove. */
+  facetsDictionaryChosen: "search.facets.dictionary_chosen",
+  /** The way from the "popular values" block into the whole control. The
+   * block is a shortcut over the busiest values, so the link has to say that
+   * the rest exist. */
+  facetsPopularAll: "search.facets.popular_all",
   /**
    * The rail's sticky footer: what the applied filters LEFT — "N listings
    * match". A PLURAL FAMILY: it counts a noun in words. Desktop filters
@@ -181,6 +210,20 @@ export const SEARCH_I18N_KEYS = {
    * `{count}` is how many chips it hides (D16). */
   filtersChipOverflow: "search.filters.chips_overflow",
 
+  // ── a partition: one template split by a value its children name ─────────
+  /**
+   * The first chip of a partition row — the parent itself, unnarrowed.
+   *
+   * Not `facetsPopularAll` reused: that one OPENS a control, this one is a
+   * CHOICE among the children (and the one that is selected by default). The
+   * two are the same word in English and stop being one the moment a
+   * translator reads either as an imperative.
+   */
+  partitionAll: "search.partition.all",
+  /** The accessible name of the chip row — a `radiogroup` with no name is
+   * announced as nothing at all. */
+  partitionLabel: "search.partition.label",
+
   // ── the way OUT of a search that found nothing ───────────────────────────
   /** Caption above the exit buttons. Not a second "nothing found" — that
    * sentence has already been said; this one says what can be done next. */
@@ -217,6 +260,19 @@ 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",
@@ -243,6 +299,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",
@@ -250,6 +318,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",
@@ -258,6 +328,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",
 
@@ -329,6 +403,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,
 ];
 
 /**
@@ -401,6 +476,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.",
@@ -415,6 +494,12 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.show_less": "Show fewer",
   "search.facets.search": "Find a filter",
   "search.facets.search_empty": "No filter matches this",
+  "search.facets.dictionary_search": "Find a value",
+  "search.facets.dictionary_empty": "No value matches this",
+  "search.facets.dictionary_chosen": "Chosen",
+  "search.facets.popular_all": "All",
+  "search.partition.all": "All",
+  "search.partition.label": "Section",
   "search.facets.match_count.one": "{count} listing matches",
   "search.facets.match_count.other": "{count} listings match",
   "search.facets.range_invalid":
@@ -452,11 +537,13 @@ export const searchI18nBundleEn: Record<string, string> = {
   "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",
@@ -466,6 +553,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":
@@ -476,6 +565,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":
     "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",
@@ -114,6 +122,12 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.show_less": "Свернуть",
   "search.facets.search": "Найти фильтр",
   "search.facets.search_empty": "Среди фильтров такого нет",
+  "search.facets.dictionary_search": "Найти значение",
+  "search.facets.dictionary_empty": "Такого значения здесь нет",
+  "search.facets.dictionary_chosen": "Выбрано",
+  "search.facets.popular_all": "Все",
+  "search.partition.all": "Все",
+  "search.partition.label": "Раздел",
   "search.facets.match_count.one": "Найдено {count} объявление",
   "search.facets.match_count.few": "Найдено {count} объявления",
   "search.facets.match_count.many": "Найдено {count} объявлений",
@@ -156,12 +170,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":
@@ -172,6 +188,8 @@ export const searchI18nBundleRu: I18nDictionary = {
     "область на карте в этой ссылке указана не полностью, поэтому она пропущена",
   "search.url.issue.range_malformed":
     "диапазону «{param}» в этой ссылке не хватает чисел, поэтому он пропущен",
+  "search.url.issue.radius_without_place":
+    "в ссылке задан радиус, но не задано место, поэтому пока ничего не сузилось — выберите место, и применится именно этот радиус",
 
   "search.degraded.title": "Что этот поиск не смог сделать",
   "search.degraded.typo_tolerance":
@@ -182,6 +200,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,12 @@ export {
   suggestTerms,
 } from "./api/types.js";
 export type {
+  FacetCategoryCount,
+  FacetLabels,
+  FacetLabelsMap,
   FacetMeta,
   FacetSelection,
+  FacetWithheldGroup,
   RankingResponse,
   Scorer,
   SearchDegradation,
@@ -95,6 +99,7 @@ export type {
 } from "./state/urlState.js";
 
 export {
+  FACET_PLAN_EVIDENCE,
   countIsEstimate,
   countKind,
   degradationAudience,
@@ -117,9 +122,16 @@ export {
 export type {
   BuildFacetGroupsInput,
   FacetGroup,
+  FacetLabelSource,
   FacetOption,
 } from "./state/facets.js";
 
+export {
+  consonantKey,
+  translitKey,
+  translitPrefixMatch,
+} from "./state/translit.js";
+
 export {
   RANGE_FEATURE_TYPES,
   buildRangeGroups,

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

@@ -8,9 +8,12 @@
  *    they would have if you swapped to them. A panel that greys the siblings
  *    out has silently converted a drill-down facet into a naive one, and the
  *    e2e leg in the spec (§7.2) exists to catch exactly that.
- * 2. **Option LABELS have one stated order: ANSWER, then schema, then the
- *    raw value** — with a host resolver between the last two, applied by
- *    `useHostFacetLabels` on what this module could not name.
+ * 2. **LABELS have one stated order: ANSWER, then schema, then the raw
+ *    term** — for the group's heading and for every option alike, with a host
+ *    resolver between the last two for options, applied by
+ *    `useHostFacetLabels` on what this module could not name. The bottom of
+ *    that order is not a label and is marked as such: `labelSource: "none"`,
+ *    a warning in development, and a data attribute on the drawn group.
  *
  *    The answer leads because it is the only source that always exists and
  *    the only one that has RESOLVED anything: `categoryFeatures` is an
@@ -50,12 +53,48 @@
 import {
   VOCABULARY_BACKED_TYPES,
   featureConfig,
-  featureName,
   featureType,
   formatFeatureValue,
 } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
-import type { FacetMeta, SearchQueryState } from "../api/types.js";
+import type { FacetLabelsMap, FacetMeta, SearchQueryState } from "../api/types.js";
+
+/**
+ * Where a caption came from — the group's heading and every option carry it,
+ * because "did anybody actually name this?" is a question two surfaces have
+ * to answer and neither can answer by looking at the string.
+ *
+ * `"none"` is the honest bottom: the raw slug for a heading, the raw index
+ * term for an option. It is not a label, it is what is printed when there is
+ * none, and it is the one value a storefront's own test asserts against.
+ */
+export type FacetLabelSource = "server" | "schema" | "host" | "none";
+
+declare const process: { readonly env: { readonly NODE_ENV?: string } };
+
+/** Slugs already complained about — one warning per slug per page load, not
+ * one per render. */
+const warnedSlugs = new Set<string>();
+
+/**
+ * A heading nobody named, said once, in development only.
+ *
+ * A raw slug in a filter panel is a wiring fault — the category has no
+ * feature definition for the slug and the server sent no label — and it is
+ * invisible to everyone but the buyer who meets it. The group still renders,
+ * because a heading a person cannot read still beats options with no heading
+ * at all; `FacetGroup.labelSource` is how a surface marks it up for a test.
+ */
+function warnUnnamedGroup(slug: string): void {
+  const env = typeof process === "undefined" ? undefined : process.env;
+  if (env?.NODE_ENV === "production") return;
+  if (warnedSlugs.has(slug)) return;
+  warnedSlugs.add(slug);
+  console.warn(
+    `[search-react] facet group "${slug}" has no label: the answer sent none ` +
+      `and no category feature defines it, so the heading is the raw slug.`
+  );
+}
 
 /**
  * Value types whose values are a BOUNDED OPTION SET — the only kind of
@@ -111,14 +150,22 @@ export interface FacetOption {
   readonly count: number | null;
   /** Resolved through the category schema; the raw value when there is none. */
   readonly label: string;
+  /** Which of the three sources named it — `"none"` means {@link label} IS
+   * the raw index term. The host seam reads this rather than comparing the
+   * two strings. */
+  readonly labelSource: FacetLabelSource;
   readonly selected: boolean;
 }
 
 /** One facet slug, with its options. */
 export interface FacetGroup {
   readonly slug: string;
-  /** The feature's display name (translated when it is a key), else the slug. */
+  /** The group's heading: the answer's own `label`, else the feature's
+   * display name, else — with a dev warning — the raw slug. */
   readonly label: string;
+  /** Which source named the heading. `"none"` is the slug standing in for a
+   * name nobody has; a surface marks it so a storefront test can fail on it. */
+  readonly labelSource: FacetLabelSource;
   /** The category-schema entry behind the slug, when the host supplied one. */
   readonly feature: FeatureDef | undefined;
   /** `false` when the server skipped this slug — counts are `null`. */
@@ -199,17 +246,17 @@ export interface BuildFacetGroupsInput {
    *    `apple` or `chernyy`. The server read that vocabulary against the
    *    snapshot the documents were written with.
    *
+   * Each entry also carries the GROUP's own `label` — the heading, resolved
+   * from the feature definition server-side and localized like everything
+   * else. It leads for the same two reasons, and it is what a category whose
+   * host passed no feature list has instead of a rail full of index slugs.
+   *
    * ABSENT on a server older than 0.4.0 — absent, not empty — which is why
    * every read of it here is optional-chained and every option falls through
    * to the schema and then to its raw self. No labels are invented at any
    * step.
    */
-  readonly facetLabels?: Readonly<
-    Record<
-      string,
-      { readonly translatable: boolean; readonly values: Readonly<Record<string, string>> }
-    >
-  >;
+  readonly facetLabels?: FacetLabelsMap;
   /** Translator for label keys. */
   readonly t?: (key: string) => string;
   /** BCP-47 tag, forwarded to `formatFeatureValue` for `date` options. */
@@ -287,11 +334,49 @@ function resolveLabel(
   slug: string,
   value: string,
   labelOptions: { t?: (key: string) => string; locale?: string }
-): string {
-  return (
-    serverLabel(input.facetLabels, slug, value, input.t) ??
-    facetOptionLabel(feature, value, labelOptions)
-  );
+): { readonly label: string; readonly labelSource: FacetLabelSource } {
+  const answer = serverLabel(input.facetLabels, slug, value, input.t);
+  if (answer !== undefined) return { label: answer, labelSource: "server" };
+  const schema = facetOptionLabel(feature, value, labelOptions);
+  // `facetOptionLabel` hands back the value unchanged for an option it
+  // cannot name, and that identity is the whole test — a formatter that
+  // returned the term is a formatter that named nothing.
+  return schema === value
+    ? { label: value, labelSource: "none" }
+    : { label: schema, labelSource: "schema" };
+}
+
+/**
+ * The group's HEADING, in the one order the fleet states: the answer, then
+ * the category schema, then the slug under a dev warning.
+ *
+ * The answer leads because it is the only source that always exists. The
+ * schema slot is optional, and at a live classified's cars branch the
+ * storefront passed an empty feature list, so every heading in the rail was
+ * a raw index slug — the make group was on screen, unlabelled, and the
+ * complaint that came back was "I cannot pick a make".
+ *
+ * The slug is not a fallback anyone may ship: it renders, because a heading
+ * beats no heading, and it renders MARKED — `labelSource: "none"`, a warning
+ * in development, and a data attribute on the drawn group.
+ */
+function resolveGroupLabel(
+  input: BuildFacetGroupsInput,
+  feature: FeatureDef | undefined,
+  slug: string
+): { readonly label: string; readonly labelSource: FacetLabelSource } {
+  const answer = input.facetLabels?.[slug]?.label;
+  if (typeof answer === "string" && answer.length > 0) {
+    return { label: translate(input.t, answer), labelSource: "server" };
+  }
+  // `featureName` falls back to the slug itself, so the def has to be asked
+  // for a NAME rather than for a name-or-slug: a def with none names nothing.
+  const declared = feature?.name;
+  if (typeof declared === "string" && declared.length > 0) {
+    return { label: translate(input.t, declared), labelSource: "schema" };
+  }
+  warnUnnamedGroup(slug);
+  return { label: slug, labelSource: "none" };
 }
 
 /**
@@ -362,6 +447,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>();
@@ -443,24 +531,62 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
 
     return {
       slug,
-      label:
-        feature === undefined
-          ? slug
-          : translate(input.t, featureName(feature)),
+      ...resolveGroupLabel(input, feature, slug),
       feature,
       counted,
       selected,
       options: values.map((value) => ({
         value,
         count: counted ? (counts[value] ?? 0) : null,
-        // The host's schema first when it actually resolves the value, the
-        // answer's caption when it does not (or when there is no schema at
-        // all), the raw value when neither knows. `facetOptionLabel` returns
-        // the value unchanged for an option it cannot name, which is what
-        // makes "did it resolve?" answerable without a second lookup.
-        label: resolveLabel(input, feature, slug, value, labelOptions),
+        // The answer's caption first, then the schema's own option table,
+        // then the raw value — and the source is carried rather than
+        // re-derived, so "did it resolve?" needs no second lookup.
+        ...resolveLabel(input, feature, slug, value, labelOptions),
         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;
 }