@stapel/search-react 0.20.0 → 0.21.0

package/src/default/LocationSummaryLine.tsx

@@ -94,6 +94,9 @@ import { GeoSheet, SUMMARY_GEO_TEST_IDS } from "./geoSheet.js";
 
 /** The class the row carries, for {@link locationLineCss}. */
 export const LOCATION_LINE_CLASS = "stapel-search-location-line";
+/** The class the ONE location control carries — the place and the offer,
+ * inside a single box. See {@link locationLineCss} for what it fixes. */
+export const LOCATION_LINE_GROUP_CLASS = "stapel-search-location-line-group";
 /** The class the shrinking half carries. */
 export const LOCATION_LINE_WHERE_CLASS = "stapel-search-location-line-where";
 /** The class the truncating label carries. */
@@ -117,6 +120,7 @@ export function locationLineCss(): string {
   const where = `.${LOCATION_LINE_WHERE_CLASS}`;
   const label = `.${LOCATION_LINE_LABEL_CLASS}`;
   const end = `.${LOCATION_LINE_END_CLASS}`;
+  const group = `.${LOCATION_LINE_GROUP_CLASS}`;
   return [
     // `min-width:0` on the row too: a flex item's default `min-width:auto`
     // is what makes a nested flex row refuse to shrink at all.
@@ -139,6 +143,35 @@ export function locationLineCss(): string {
       `text-overflow:ellipsis;white-space:nowrap}`,
     // The word a person is looking for never loses a pixel to a place name.
     `${end}{flex:0 0 auto}`,
+    // ── ONE control, not two red links at opposite ends of the page ────────
+    //
+    // Measured on a live 1440px leaf: the row is 992px wide, "📍 Searching
+    // everywhere" sat at x=370 and "Near me · Within 25 km" at x=776, both
+    // drawn in the same brand red, with ~400px of air between them and
+    // nothing — no border, no ground, no heading — saying they were about the
+    // same thing. Two identical-looking links at opposite ends of a strip are
+    // read as two unrelated controls, which is what they looked like.
+    //
+    // So the place and the offer share ONE box with a border and a ground,
+    // sitting together at the leading edge, with a hairline between them: the
+    // eye gets a single object that says where this search is looking and
+    // offers the one move that would change it. The border comes from the
+    // role token, so it is right in both themes by construction.
+    // `min-inline-size:0` explicitly, and `flex-shrink` on the box rather
+    // than on its contents: a flex item's `min-width:auto` refuses to go
+    // below its own content, so without this the group pushed the filters
+    // door off the end of a 390px row instead of letting the place name give
+    // way — which is the half that can.
+    `${group}{display:flex;align-items:stretch;flex:0 1 auto;min-inline-size:0;` +
+      `border:1px solid ${cssVar("border")};border-radius:${String(radii.md)}px;` +
+      `background:${cssVar("surface-raised")};overflow:hidden}`,
+    // The two halves are separated by the box's own line, never by a gap: a
+    // gap inside a bordered group reads as two groups again.
+    `${group}>*+*{border-inline-start:1px solid ${cssVar("border")}}`,
+    `${group}>*{border-radius:0}`,
+    // Both halves pay for their own breathing room; the antd Button's inline
+    // padding is zeroed above so the box, not the button, sets the measure.
+    `${group}>*{padding-inline:${String(spacing[2])}px}`,
   ].join("");
 }
 
@@ -149,7 +182,9 @@ const ROW: CSSProperties = { width: "100%" };
 /** The shrinking half. The flex rules it needs live in the hoisted sheet
  * (they have to reach antd's own wrapper span); this is the chrome. */
 const LOCATION: CSSProperties = {
-  paddingInline: 0,
+  // No `paddingInline` here: the group's sheet sets it for both halves, and
+  // an inline style would beat the sheet and leave one half flush against the
+  // border while the other breathed.
   textAlign: "start",
 };
 
@@ -159,7 +194,7 @@ const PIN: CSSProperties = { flex: "0 0 auto", display: "inline-flex" };
 
 /** The offer. It never shrinks: it is three words and a number, and half of
  * "Near me" is not an offer. */
-const OFFER: CSSProperties = { flex: "0 0 auto", paddingInline: 0 };
+const OFFER: CSSProperties = { flex: "0 0 auto" };
 
 /**
  * The count, IN the flow.
@@ -239,7 +274,8 @@ export function LocationSummaryLine(
   props: LocationSummaryLineProps
 ): ReactElement {
   const t = useT();
-  const { state, activeFilters, geoOffer, acceptGeoOffer } = useSearchState();
+  const { state, activeFilters, geoOffer, geoIsOffer, acceptGeoOffer } =
+    useSearchState();
   const [open, setOpen] = useState(false);
   const geo = state.geo;
 
@@ -257,13 +293,25 @@ export function LocationSummaryLine(
   // the question), so this row never shows an offer beside a place.
   const offerRadius =
     geoOffer !== undefined && geoOffer.kind === "center" && geoOffer.radiusKm !== undefined
-      ? t(SEARCH_I18N_KEYS.geoRadiusKm, { km: geoOffer.radiusKm })
+      ? t(SEARCH_I18N_KEYS.geoRadiusKmShort, { km: geoOffer.radiusKm })
       : undefined;
 
+  // What the line CALLS the place it is looking at.
+  //
+  // The host's name wins — it is the only one that can be checked by a reader
+  // — then the fact the provider holds, and only then the shape of the
+  // constraint. The middle arm is D184's second half: pressing "Near me"
+  // turned this line into "A chosen place on the map" for a person who had
+  // never opened a map. `geoIsOffer` is the provider reporting how the search
+  // came to be here, rather than this file inferring it from three numbers
+  // that look the same whatever produced them.
   const where: ReactNode =
     geo === undefined
       ? t(SEARCH_I18N_KEYS.geoEverywhere)
-      : (props.geoLabel ?? geoSummaryFallback(geo, t));
+      : (props.geoLabel ??
+        (geoIsOffer
+          ? t(SEARCH_I18N_KEYS.geoNearYou)
+          : geoSummaryFallback(geo, t)));
 
   return (
     <>
@@ -279,60 +327,73 @@ export function LocationSummaryLine(
         data-testid="search-location-summary"
         data-geo={geo === undefined ? "off" : "on"}
       >
-        {/* The glyph is rendered as a CHILD rather than through antd's `icon`
-            prop: the icon slot sits outside the wrapper span, so the label
-            beside it could not be given a min-width of its own — and a label
-            that cannot shrink is a label that overflows. */}
-        <Button
-          type="link"
-          style={LOCATION}
-          className={LOCATION_LINE_WHERE_CLASS}
-          data-testid="search-location-open"
-          data-analytics="none"
-          data-analytics-reason="opening the location sheet is a read, not a flow step"
-          onClick={() => {
-            setOpen(true);
-          }}
+        {/* ONE control: where this search is looking, and — while the
+            question is still open — the one move that would change it. See
+            `locationLineCss` for the measurement that made them one box. */}
+        <div
+          className={LOCATION_LINE_GROUP_CLASS}
+          data-testid="search-location-group"
         >
-          <span style={PIN}>
-            <PinGlyph />
-          </span>
-          <span
-            className={LOCATION_LINE_LABEL_CLASS}
-            data-testid="search-location-label"
-          >
-            {where}
-            {radius !== undefined && (
-              <span data-testid="search-location-radius">
-                {" · "}
-                {radius}
-              </span>
-            )}
-          </span>
-        </Button>
+          {/* The glyph is rendered as a CHILD rather than through antd's
+              `icon` prop: the icon slot sits outside the wrapper span, so the
+              label beside it could not be given a min-width of its own — and
+              a label that cannot shrink is a label that overflows.
 
-        {/* The offer, and nothing is applied until it is pressed. Drawn only
-            when the host has a position to offer AND the search carries no
-            location of its own — the provider enforces the second half, so
-            this is one condition, not two that could disagree. */}
-        {geoOffer !== undefined && (
+              `type="text"`, not `type="link"`: this half is a STATEMENT about
+              where the search is looking, and painting it the brand colour
+              made it indistinguishable from the offer beside it. The offer
+              keeps the colour, because the offer is the action. */}
           <Button
-            type="link"
-            style={OFFER}
-            data-testid="search-location-offer"
+            type="text"
+            style={LOCATION}
+            className={LOCATION_LINE_WHERE_CLASS}
+            data-testid="search-location-open"
             data-analytics="none"
-            data-analytics-reason="applying a filter the person pressed is search state, and search state is the URL"
-            onClick={acceptGeoOffer}
+            data-analytics-reason="opening the location sheet is a read, not a flow step"
+            onClick={() => {
+              setOpen(true);
+            }}
           >
-            {t(SEARCH_I18N_KEYS.geoNearMe)}
-            {offerRadius !== undefined && (
-              <span data-testid="search-location-offer-radius">
-                {" · "}
-                {offerRadius}
-              </span>
-            )}
+            <span style={PIN}>
+              <PinGlyph />
+            </span>
+            <span
+              className={LOCATION_LINE_LABEL_CLASS}
+              data-testid="search-location-label"
+            >
+              {where}
+              {radius !== undefined && (
+                <span data-testid="search-location-radius">
+                  {" · "}
+                  {radius}
+                </span>
+              )}
+            </span>
           </Button>
-        )}
+
+          {/* The offer, and nothing is applied until it is pressed. Drawn only
+              when the host has a position to offer AND the search carries no
+              location of its own — the provider enforces the second half, so
+              this is one condition, not two that could disagree. */}
+          {geoOffer !== undefined && (
+            <Button
+              type="link"
+              style={OFFER}
+              data-testid="search-location-offer"
+              data-analytics="none"
+              data-analytics-reason="applying a filter the person pressed is search state, and search state is the URL"
+              onClick={acceptGeoOffer}
+            >
+              {t(SEARCH_I18N_KEYS.geoNearMe)}
+              {offerRadius !== undefined && (
+                <span data-testid="search-location-offer-radius">
+                  {" · "}
+                  {offerRadius}
+                </span>
+              )}
+            </Button>
+          )}
+        </div>
 
         {/* "Filters", not "All filters": this end of the row shares 390px
             with a place name that can run to fifteen characters, and the word

package/src/default/SearchPage.tsx

@@ -426,6 +426,11 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const filtersEmpty =
     facets.state.status === "ready" &&
     facets.state.data.length === 0 &&
+    // Zero groups is not zero filters: `withheld` names groups the server
+    // counted and held back for covering too little of the result set, and
+    // the panel's job is to say how many (D175). Skipping the column would
+    // put that sentence nowhere.
+    facets.withheld.length === 0 &&
     facets.activeFilters === 0 &&
     ranges.length === 0 &&
     state.category === undefined &&

package/src/headless/FacetPanel.tsx

@@ -2,9 +2,15 @@ import type { ReactNode } from "react";
 import { loadStateFromQuery, mapLoad, useT } from "@stapel/core";
 import type { LoadState } from "@stapel/core";
 import type { FeatureDef } from "@stapel/attributes-react";
-import type { FacetMeta, SearchRange } from "../api/types.js";
+import type {
+  FacetCategoryCount,
+  FacetMeta,
+  FacetWithheldGroup,
+  SearchRange,
+} from "../api/types.js";
 import { useSearchQuery } from "../model/queries.js";
 import { buildFacetGroups } from "../state/facets.js";
+import { FACET_PLAN_EVIDENCE } from "../state/degradations.js";
 import type { FacetGroup } from "../state/facets.js";
 import { useHostFacetLabels } from "./useFacetLabels.js";
 import type { FacetLabelResolver } from "./useFacetLabels.js";
@@ -51,6 +57,34 @@ export interface FacetPanelBag {
   readonly currency: string | undefined;
   /** Size of the largest counted set — the number `approximate` is about. */
   readonly candidates: number;
+  /**
+   * Groups the counter COUNTED and then held back, because their buckets
+   * describe too little of the result set. Not empty means the panel may
+   * NOT say "this search offers no filters" — it says how many, instead.
+   */
+  readonly withheld: readonly FacetWithheldGroup[];
+  /**
+   * The categories this answer's candidate set is made of, busiest first —
+   * the evidence the plan was drawn from, and the counted category filter a
+   * text search has no other way to offer. Empty when the plan is the
+   * queried category's own. `category` is the same slash-joined id path
+   * `SearchQueryState.category` takes.
+   */
+  readonly categories: readonly FacetCategoryCount[];
+  /**
+   * Where the plan came from: `"category"` (the queried category's own
+   * authored schema) or `"evidence"` (the categories the candidate set
+   * actually contains).
+   */
+  readonly plan: string;
+  /**
+   * True when the server could not work out a plan AT ALL — the engine has
+   * no `category_counts` verb (`degraded: ["facet_plan_evidence"]`). An
+   * empty panel then means "we do not know", so a skin must not print
+   * "there are no filters" over it; the degradation notice is what tells
+   * the reader.
+   */
+  readonly planUnavailable: boolean;
   /** Facet values + ranges + geo currently applied. */
   readonly activeFilters: number;
 
@@ -67,6 +101,9 @@ const EMPTY_META: FacetMeta = {
   skipped: [],
   dropped_filters: [],
   core_ranges: [],
+  plan: "category",
+  withheld: [],
+  categories: [],
 };
 
 /**
@@ -174,6 +211,17 @@ export function useFacetPanel(props: {
             ?.card?.["currency"] as string | undefined
         : undefined,
     candidates: meta.candidates,
+    withheld: meta.withheld ?? [],
+    categories: meta.categories ?? [],
+    plan: meta.plan ?? "category",
+    // Read off the raw list rather than through `parseDegradations`: the
+    // question is whether THIS answer supports the sentence "no filters",
+    // and the banner's own parsing is a different job on a different
+    // surface. Guarded on the READY state, never flattened — a query still
+    // in flight has not said anything about its facet plan.
+    planUnavailable:
+      envelope.status === "ready" &&
+      envelope.data.degraded.includes(FACET_PLAN_EVIDENCE),
     activeFilters,
     toggle: toggleFilter,
     setRange,

package/src/headless/SearchStateProvider.tsx

@@ -71,6 +71,21 @@ export interface SearchStateBag {
    * 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;
@@ -92,6 +107,29 @@ export interface SearchStateBag {
   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 {
@@ -178,6 +216,23 @@ export function SearchStateProvider(
 
   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 }
@@ -193,7 +248,8 @@ export function SearchStateProvider(
       // — 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 ? geoOffer : undefined,
+      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
@@ -209,10 +265,10 @@ export function SearchStateProvider(
         apply(patchSearchState(state, { geo }));
       },
       acceptGeoOffer: () => {
-        if (geoOffer === undefined || state.geo !== undefined) return;
+        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: geoOffer }));
+        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 }),

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,12 +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":
@@ -141,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":
@@ -151,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,6 +228,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 +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",
@@ -250,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",
@@ -258,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",
 
@@ -329,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,
 ];
 
 /**
@@ -401,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.",
@@ -452,11 +499,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 +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":
@@ -476,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,12 +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":
@@ -172,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":
@@ -182,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,