@stapel/search-react 0.16.0 → 0.18.1

package/src/default/FacetPanelPane.tsx

@@ -35,17 +35,44 @@
  * than a silent absence — and, in every build, any constraint the URL already
  * carries gets a control that REMOVES it. A shared link that narrows to a
  * category or a point must never leave a person with no way to widen it again.
+ *
+ * ── The panel opens what the answer argues for, and closes the rest ────────
+ *
+ * Measured on a live classified deployment's cars leaf at 1440×900: this
+ * panel, in a 280px rail, was 5717px tall — 40 groups, 118 checkboxes, 66
+ * fields, one flat column whose tail no scroll a person actually performs
+ * ever reaches. The phone sheet drew the same column six screens deep.
+ *
+ * So the groups are disclosures now, and WHICH open is decided here, from
+ * evidence the panel already holds: a group with any chosen value is always
+ * open (a constraint must keep its control in sight), and otherwise the top
+ * {@link FACET_OPEN_GROUPS} counted groups by {@link facetCoverage} — the sum
+ * of an axis's counts is the answer's own statement of how many documents
+ * carry it, the same reasoning the chip row sorts its band by. Everything
+ * else starts as a header, one click from whole. A group the server never
+ * counted sums to zero and therefore never opens uninvited, which is what
+ * removes the wall of "not counted" rows from the default view without
+ * deleting one of them.
+ *
+ * From {@link FACET_SEARCH_THRESHOLD} groups up the panel also takes a search
+ * of ITSELF — a person who cannot scan forty headers should not have to open
+ * them one by one to find the axle count. It narrows by group or option
+ * label, opens what it matches, and touches presentation only: the URL is
+ * state and a panel query is not.
  */
+import { useState } from "react";
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import {
   Alert,
   Button,
   Divider,
   Flex,
+  Input,
   InputNumber,
   Typography,
+  theme,
 } from "antd";
-import { SlotPlaceholder, isDevBuild, useT } from "@stapel/core";
+import { SlotPlaceholder, isDevBuild, useT, useTPlural } from "@stapel/core";
 import {
   EmptyState,
   ErrorAlert,
@@ -59,6 +86,9 @@ import type { SearchGeo } from "../api/types.js";
 import { FacetPanel } from "../headless/FacetPanel.js";
 import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
+import { useAppliedCount } from "../headless/useAppliedCount.js";
+import { facetCoverage } from "../state/facets.js";
+import type { FacetGroup } from "../state/facets.js";
 import { FacetGroupControl } from "./FacetGroupControl.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
@@ -123,6 +153,21 @@ const FACET_CLEAR: CSSProperties = {
   textAlign: "start",
 };
 
+/**
+ * How many counted groups open by default — beyond the ones with chosen
+ * values, which always do. Five open groups at the default type step fill
+ * roughly one 900px window of the rail: the panel's first screen is the five
+ * axes this corpus is most narrowed by, and everything after is a header.
+ */
+export const FACET_OPEN_GROUPS = 5;
+
+/**
+ * From how many groups the panel offers a search of itself. Under six the
+ * headers fit a glance and a box would be chrome over nothing; the measured
+ * leaf had forty.
+ */
+export const FACET_SEARCH_THRESHOLD = 6;
+
 /** What a host's category control is handed. */
 export interface CategoryFilterSlotProps {
   /** The `root/leaf` path the search is narrowed to, if any. */
@@ -210,6 +255,87 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
    * on a staging surface. Nothing else changes with it.
    */
   readonly skippedNotice?: boolean;
+  /**
+   * Draw the sticky footer inside the panel: the live result count as the
+   * bar's strong text, and the clear-all control (which then moves out of the
+   * heading row — one control, not two) beside it. Default `false`.
+   *
+   * `<SearchPage>` turns it on for the desktop RAIL only. Desktop filters
+   * apply instantly, so the bar is FEEDBACK plus the way out, not an apply
+   * button — which is exactly why the phone sheet must not get it: the sheet
+   * already closes through its own "Show N results" footer, and a second
+   * count-bearing bar above that one would be the same sentence twice.
+   */
+  readonly footerBar?: boolean;
+}
+
+/**
+ * The rail's sticky floor: what the filters DID (the live count), and the way
+ * out of them (clear all). It sticks to the bottom of the rail's own scroll,
+ * so however deep the panel goes the answer stays on screen.
+ *
+ * The count reuses `useAppliedCount` — the answer already in cache, never a
+ * second request — and its honesty rules: an exact count gets the counted
+ * noun ("N listings match"), a floor keeps the existing "N+" family, and an
+ * engine that cannot say gets NO number, because a fabricated one on the
+ * surface that reports what filtering did is worse than silence. With
+ * nothing to say and nothing to clear, no bar.
+ */
+function RailFooterBar(props: {
+  readonly activeFilters: number;
+  readonly clearAll: () => void;
+}): ReactElement | null {
+  const t = useT();
+  const tPlural = useTPlural();
+  // The token bag of the nearest theme, so the bar's ground and hairline are
+  // the panel's own in both modes — a hard-coded white floor would glow in
+  // the dark theme.
+  const { token } = theme.useToken();
+  const applied = useAppliedCount();
+  const countText =
+    applied.count === null || applied.kind === "unknown"
+      ? null
+      : tPlural(
+          applied.kind === "at_least"
+            ? SEARCH_I18N_KEYS.resultsCountAtLeast
+            : SEARCH_I18N_KEYS.facetsMatchCount,
+          { count: applied.count }
+        );
+  if (countText === null && props.activeFilters === 0) return null;
+  return (
+    <div
+      data-testid="facets-footer-bar"
+      style={{
+        position: "sticky",
+        bottom: 0,
+        // Opaque, or the options scrolling under the bar read THROUGH it.
+        background: token.colorBgContainer,
+        borderBlockStart: `1px solid ${token.colorSplit}`,
+        paddingBlockStart: spacing[2],
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "flex-start",
+        gap: spacing[2],
+      }}
+    >
+      {countText !== null && (
+        <Typography.Text strong data-testid="facets-footer-count">
+          {countText}
+        </Typography.Text>
+      )}
+      {props.activeFilters > 0 && (
+        <Button
+          style={FACET_CLEAR}
+          onClick={props.clearAll}
+          data-analytics="none"
+          data-analytics-reason="a filter is a read, not a flow step"
+          data-testid="facets-clear-all"
+        >
+          {t(SEARCH_I18N_KEYS.facetsClearAll, { count: props.activeFilters })}
+        </Button>
+      )}
+    </div>
+  );
 }
 
 /** The category constraint: the host's control, or the door out of it. */
@@ -401,6 +527,10 @@ function skippedNames(
 export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
   const t = useT();
   const { state } = useSearchState();
+  // The panel-search's text. COMPONENT state on purpose: it narrows how the
+  // panel is drawn, never what the search is, so it must not survive into a
+  // shared link the way everything in `useSearchState` does.
+  const [filterQuery, setFilterQuery] = useState("");
 
   return (
     <SkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
@@ -455,7 +585,10 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                   {props.heading ?? t(SEARCH_I18N_KEYS.facetsTitle)}
                 </Typography.Title>
               )}
-              {bag.activeFilters > 0 && (
+              {/* With the footer bar on, clear-all lives THERE — beside the
+                  count it acts on — and drawing it here too would be two
+                  identical exits one panel apart. */}
+              {bag.activeFilters > 0 && props.footerBar !== true && (
                 <Button
                   style={FACET_CLEAR}
                   onClick={bag.clearAll}
@@ -538,35 +671,103 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 />
               )}
             >
-              {(groups) => (
-                <Flex vertical gap={spacing[4]}>
-                  {/* A group with no options is a heading with nothing under
-                      it. What is left in that state after `buildFacetGroups`
-                      learned to read the schema is the genuinely unanswerable
-                      case: a `ref_select` whose config is a bare pointer into
-                      a vocabulary this pair cannot read. A heading with no
-                      control under it names nothing, so it is not drawn. */}
-                  {/* Each group draws itself the way its own schema says:
-                      pills for a single-choice facet, indented children for a
-                      hierarchical one, a fold for a long one. The panel does
-                      not decide — `facetGroupShape` reads the same config keys
-                      the attributes editor reads, so a facet cannot look one
-                      way here and another way in the composer. */}
-                  {groups
-                    .filter((group) => group.options.length > 0)
-                    .map((group) => (
+              {(groups) => {
+                // A group with no options is a heading with nothing under
+                // it. What is left in that state after `buildFacetGroups`
+                // learned to read the schema is the genuinely unanswerable
+                // case: a `ref_select` whose config is a bare pointer into
+                // a vocabulary this pair cannot read. A heading with no
+                // control under it names nothing, so it is not drawn.
+                const drawable = groups.filter(
+                  (group) => group.options.length > 0
+                );
+                // Which groups OPEN — see the module note. Chosen groups are
+                // open unconditionally below; here the answer's evidence
+                // picks the rest: the top counted groups by coverage, and a
+                // group the server never counted sums to zero, so the wall
+                // of "not counted" rows starts as headers.
+                const openByEvidence = new Set(
+                  drawable
+                    .filter((group) => group.counted)
+                    .map((group) => [group, facetCoverage(group)] as const)
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, FACET_OPEN_GROUPS)
+                    .map(([group]) => group.slug)
+                );
+                const searchable = drawable.length >= FACET_SEARCH_THRESHOLD;
+                const needle = searchable
+                  ? filterQuery.trim().toLowerCase()
+                  : "";
+                const matches = (group: FacetGroup): boolean =>
+                  group.label.toLowerCase().includes(needle) ||
+                  group.options.some((option) =>
+                    option.label.toLowerCase().includes(needle)
+                  );
+                const listed =
+                  needle === "" ? drawable : drawable.filter(matches);
+                return (
+                  <Flex vertical gap={spacing[4]}>
+                    {searchable && (
+                      <Input
+                        allowClear
+                        value={filterQuery}
+                        placeholder={t(SEARCH_I18N_KEYS.facetsSearch)}
+                        aria-label={t(SEARCH_I18N_KEYS.facetsSearch)}
+                        data-testid="facets-search"
+                        onChange={(event) => {
+                          setFilterQuery(event.target.value);
+                        }}
+                      />
+                    )}
+                    {/* The query missed. The groups are still there — one
+                        cleared box away — so this is the panel-search's empty
+                        state, not the panel's. */}
+                    {needle !== "" && listed.length === 0 && (
+                      <EmptyState
+                        compact
+                        title={t(SEARCH_I18N_KEYS.facetsSearchEmpty)}
+                        testId="facets-search-empty"
+                      />
+                    )}
+                    {/* Each group draws itself the way its own schema says:
+                        pills for a single-choice facet, indented children for a
+                        hierarchical one, a fold for a long one. The panel does
+                        not decide — `facetGroupShape` reads the same config keys
+                        the attributes editor reads, so a facet cannot look one
+                        way here and another way in the composer. */}
+                    {/* The key changes with the query's presence ON PURPOSE:
+                        `defaultOpen` is an initial value, and a group the
+                        panel-search matched has to render OPEN — a hit behind
+                        a closed header is not an answer. Remounting is the
+                        honest way to re-ask the question; the person's own
+                        opens and closes come back when the box clears. */}
+                    {listed.map((group) => (
                       <FacetGroupControl
-                        key={group.slug}
+                        key={needle === "" ? group.slug : `${group.slug}:match`}
                         group={group}
                         onToggle={bag.toggle}
+                        collapsible
+                        defaultOpen={
+                          needle !== "" ||
+                          group.selected.length > 0 ||
+                          openByEvidence.has(group.slug)
+                        }
                       />
                     ))}
-                  <Typography.Text type="secondary">
-                    {t(SEARCH_I18N_KEYS.facetsDrillDownHint)}
-                  </Typography.Text>
-                </Flex>
-              )}
+                    <Typography.Text type="secondary">
+                      {t(SEARCH_I18N_KEYS.facetsDrillDownHint)}
+                    </Typography.Text>
+                  </Flex>
+                );
+              }}
             </LoadList>
+
+            {props.footerBar === true && (
+              <RailFooterBar
+                activeFilters={bag.activeFilters}
+                clearAll={bag.clearAll}
+              />
+            )}
           </Flex>
           );
         }}

package/src/default/FilterChips.tsx

@@ -133,6 +133,7 @@ import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import type { RangeGroup } from "../state/ranges.js";
+import { facetCoverage } from "../state/facets.js";
 import type { FacetGroup } from "../state/facets.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { FacetGroupControl } from "./FacetGroupControl.js";
@@ -242,10 +243,48 @@ export function orderChipFilters(
   return [...specs].sort((a, b) => {
     const applied = Number(specApplied(b)) - Number(specApplied(a));
     if (applied !== 0) return applied;
-    return CHIP_BAND_ORDER.indexOf(a.band) - CHIP_BAND_ORDER.indexOf(b.band);
+    const band = CHIP_BAND_ORDER.indexOf(a.band) - CHIP_BAND_ORDER.indexOf(b.band);
+    if (band !== 0) return band;
+    // WITHIN the counted-facet band: coverage — the answer's own evidence of
+    // which axes this corpus actually fills (D16 reopen: an imported
+    // catalogue gave the phones leaf option tables for its wholesale
+    // plumbing, and schema order put them ahead of the brand). A group the
+    // server did not count sums to zero and trails every counted one; ties
+    // keep the authored order because the sort is stable.
+    if (a.band === "facet" && b.band === "facet") {
+      return facetCoverage(b.facet) - facetCoverage(a.facet);
+    }
+    return 0;
   });
 }
 
+/**
+ * How many banded chips the row draws before the "more" door — enough for the
+ * axes with real evidence behind them, small enough that the tail of a
+ * 44-axis cars leaf lives in the panel instead of in four flicks. A host
+ * passes `maxRowChips` to move it, or `null` to disable the door.
+ */
+export const CHIP_ROW_CAP = 8;
+
+/**
+ * The visible row and what the door owes: the first `max` specs — and EVERY
+ * applied one, however many, because a constraint on screen must keep the
+ * control that removes it (the same rule the barren filter follows). The
+ * overflow count is what the door chip prints; the chips behind it are not
+ * deleted, they are the panel's — one tap behind the door itself.
+ */
+export function capChipRow(
+  specs: readonly ChipSpec[],
+  max: number | null
+): { readonly visible: readonly ChipSpec[]; readonly overflow: number } {
+  if (max === null || specs.length <= max) {
+    return { visible: specs, overflow: 0 };
+  }
+  const applied = specs.filter(specApplied).length;
+  const cut = Math.max(max, applied);
+  return { visible: specs.slice(0, cut), overflow: specs.length - cut };
+}
+
 export interface FilterChipsProps {
   /** The category's feature schema — the source of option labels, of which
    * slugs get a range chip, of which slugs are choosable at all, and of how
@@ -295,6 +334,13 @@ export interface FilterChipsProps {
   /** Open the whole panel — the leading chip's action. The page owns that
    * sheet, because the page is the surface it covers. */
   readonly onOpenAll: () => void;
+  /**
+   * The row's chip budget before the "more" door — see {@link CHIP_ROW_CAP}
+   * (the default). `null` draws every chip, door-less, as the row did before
+   * it was capped. Applied filters never count against the budget's loss:
+   * they are always drawn.
+   */
+  readonly maxRowChips?: number | null;
   /**
    * Draw the location chip. Default `true`.
    *
@@ -437,7 +483,11 @@ export function FilterChips(props: FilterChipsProps): ReactElement | null {
   // need. Applied ones stay: a constraint always keeps the control that
   // removes it.
   const barren = bag.counted.length > 0 && bag.candidates === 0;
-  const ordered = orderChipFilters(ranges, groups, { barren });
+  const orderedAll = orderChipFilters(ranges, groups, { barren });
+  const { visible: ordered, overflow } = capChipRow(
+    orderedAll,
+    props.maxRowChips === undefined ? CHIP_ROW_CAP : props.maxRowChips
+  );
 
   const geo = state.geo;
   const showGeoChip =
@@ -569,6 +619,23 @@ export function FilterChips(props: FilterChipsProps): ReactElement | null {
             </Button>
           )
         )}
+
+        {/* The "more" door (D16): the capped tail is not deleted, it is one
+            tap away — this opens the SAME full panel the leading circle
+            does, where every cut control lives whole. The count keeps the
+            door honest about how much it is standing in front of. */}
+        {overflow > 0 && (
+          <Button
+            style={CHIP}
+            shape="round"
+            data-testid="search-chips-overflow"
+            data-analytics="none"
+            data-analytics-reason="opening the filter sheet is a read, not a flow step"
+            onClick={props.onOpenAll}
+          >
+            {t(SEARCH_I18N_KEYS.filtersChipOverflow, { count: overflow })}
+          </Button>
+        )}
       </div>
 
       {/* One sheet per chip, rendered only for the open one: a dozen mounted

package/src/default/SearchPage.tsx

@@ -139,6 +139,15 @@ const RAIL: CSSProperties = {
   maxHeight: "100dvh",
   overflowY: "auto",
   overscrollBehavior: "contain",
+  // The inner scroll must be VISIBLE. On overlay-scrollbar platforms (every
+  // Mac by default, most phones) an `overflow-y: auto` column shows no
+  // scrollbar until a pointer happens to scroll INSIDE it — so a rail taller
+  // than the window is indistinguishable from a rail that ends at the fold,
+  // and the walker measured 5717px of panel whose tail nothing signposted.
+  // A thin, always-there scrollbar is the sign there is more; the stable
+  // gutter keeps the panel's right edge from jumping when it appears.
+  scrollbarWidth: "thin",
+  scrollbarGutter: "stable",
   // Room for the focus ring of the last control against the scroll edge.
   paddingBlockEnd: spacing[2],
 };
@@ -424,9 +433,14 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           a hole, just a smaller one. */}
       {/* In the sheet the dialog's own title already says "Filters"; the panel
           repeating it printed the word twice, one line apart. */}
+      {/* Per layout: the sheet gets no second "Filters" title (the dialog owns
+          one) and no footer bar — its own "Show N results" footer is already
+          the count AND the exit. The rail gets the sticky footer bar: desktop
+          filters apply instantly, and without it the only feedback was a
+          result count scrolled out of sight above the fold. */}
       {filtersEmpty ? null : (
         <FacetPanelPane
-          {...(layout === "sheet" ? { heading: null } : {})}
+          {...(layout === "sheet" ? { heading: null } : { footerBar: true })}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(props.renderEmptyExits !== undefined
             ? { renderEmptyExits: props.renderEmptyExits }

package/src/default/SearchResultsPane.tsx

@@ -70,20 +70,33 @@ export type SearchResultsRenderer = (
  * width of whatever it was dropped into — the visual pass measured a 2560px
  * pane with four cards floating at the top of it and a status row 1350px from
  * the buttons that act on it (class C-NOMAXW).
+ *
+ * 1400 and not the 1120 it started at: a card GRID is not prose — its rows
+ * have no line to lose the thread of — so its measure is the fleet's widest
+ * content column, not a paragraph's. At 1120 the cap quietly overrode the
+ * grid's own 260px floor (a 1440px desktop drew three 363px cards inside a
+ * 1392px content column, the very hole the floor was lowered to fill); at
+ * 1400 the floor decides — five columns open, four beside the filter rail —
+ * and the 2560px pane the constant was written against is still capped.
  */
-export const RESULTS_MAX_WIDTH = 1120;
+export const RESULTS_MAX_WIDTH = 1400;
 
 /**
- * The results grid. `auto-fill` + `minmax(280px, 1fr)`: as many columns as fit,
- * each at least a readable card and never wider than its share — a catalogue
- * on a 1400px desktop is four columns, not four full-bleed rows, and the same
+ * The results grid. `auto-fill` + `minmax(260px, 1fr)`: as many columns as fit,
+ * each at least a readable card and never wider than its share — and the same
  * declaration collapses to one column on a phone with no breakpoint to
- * maintain. 280px is the width below which the default card's title, price and
- * location stop fitting on their own lines.
+ * maintain.
+ *
+ * The floor was 280px and is 260 deliberately: at a 1400px content measure the
+ * grid now draws five columns instead of three wide ones, and beside the 280px
+ * filter rail, four. The default card's own minimum — title, price and
+ * location each on their own line — still fits at 260; the 20px the old floor
+ * bought went into card whitespace, not into legibility, and cost a whole
+ * column of listings on the reference desktop.
  */
 const RESULTS_GRID: CSSProperties = {
   display: "grid",
-  gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))",
+  gridTemplateColumns: "repeat(auto-fill, minmax(260px, 1fr))",
   gap: spacing[3],
   alignItems: "stretch",
 };

package/src/default/SortSelect.tsx

@@ -136,7 +136,9 @@ export function SortSelect(props: SortSelectProps): ReactElement {
   }
 
   return (
-    <GatedControl gate={distance} testId="search-sort-gate">
+    // `annotate`: the gate judges ONE option, not the control. Suppressing
+    // the select would take away every sort, which is not what is blocked.
+    <GatedControl gate={distance} whenBlocked="annotate" testId="search-sort-gate">
       {(bind) => (
         <Flex gap={spacing[2]} align="center">
           <Typography.Text type="secondary" aria-hidden="true">

package/src/default/index.ts

@@ -51,8 +51,10 @@ export type {
 export {
   FilterChips,
   CHIP_BAND_ORDER,
+  CHIP_ROW_CAP,
   CHIP_ROW_CLASS,
   CHIP_ROW_STYLE_HREF,
+  capChipRow,
   categoryLeaf,
   chipRowCss,
   orderChipFilters,

package/src/i18n/es.ts

@@ -87,6 +87,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.range_to_aria": "{feature}, hasta",
   "search.facets.show_all": "Ver todos ({count})",
   "search.facets.show_less": "Ver menos",
+  "search.facets.search": "Buscar un filtro",
+  "search.facets.search_empty": "Ningún filtro coincide con esto",
+  "search.facets.match_count.one": "{count} anuncio coincide",
+  "search.facets.match_count.other": "{count} anuncios coinciden",
   "search.facets.range_invalid":
     "«Desde» es mayor que «hasta», así que nada podría coincidir. Intercámbialos para aplicar el rango.",
 
@@ -101,6 +105,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.filters.all": "Todos los filtros",
   "search.filters.short": "Filtros",
   "search.filters.chip_more": ", +{count}",
+  "search.filters.chips_overflow": "Más · {count}",
 
   "search.empty.exits_title": "Prueba a ampliar la búsqueda",
   "search.empty.up_a_level": "Subir un nivel",

package/src/i18n/keys.ts

@@ -138,6 +138,22 @@ export const SEARCH_I18N_KEYS = {
    * tail is longer than one row. */
   facetsShowAll: "search.facets.show_all",
   facetsShowLess: "search.facets.show_less",
+  /** The box that searches the FILTER PANEL itself — drawn from six groups
+   * up, because a panel a person can no longer scan is a panel they have to
+   * query. It narrows presentation only and never touches the URL. */
+  facetsSearch: "search.facets.search",
+  /** Said where the groups were when the panel-search matches none of them.
+   * Distinct from `facetsEmpty`, which says the SEARCH offers no filters —
+   * here the filters exist and the query missed. */
+  facetsSearchEmpty: "search.facets.search_empty",
+  /**
+   * The rail's sticky footer: what the applied filters LEFT — "N listings
+   * match". A PLURAL FAMILY: it counts a noun in words. Desktop filters
+   * apply instantly, so this is feedback, not an apply button; the floor
+   * case (`at_least`) reuses `resultsCountAtLeast` rather than growing a
+   * second family for the same number.
+   */
+  facetsMatchCount: "search.facets.match_count",
 
   // ── the filter panel as a whole (phone sheet + host slots) ───────────────
   filtersOpen: "search.filters.open",
@@ -161,6 +177,9 @@ export const SEARCH_I18N_KEYS = {
   /** A chip filtering on more than one value: "Bosch, +2". Not a plural
    * family — nothing is being counted in words. */
   filtersChipMore: "search.filters.chip_more",
+  /** The chip standing in for the row's capped tail — opens the full panel.
+   * `{count}` is how many chips it hides (D16). */
+  filtersChipOverflow: "search.filters.chips_overflow",
 
   // ── the way OUT of a search that found nothing ───────────────────────────
   /** Caption above the exit buttons. Not a second "nothing found" — that
@@ -308,6 +327,7 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.filtersShowCount,
   SEARCH_I18N_KEYS.filtersShowCountAtLeast,
   SEARCH_I18N_KEYS.boxCategoryCount,
+  SEARCH_I18N_KEYS.facetsMatchCount,
 ];
 
 /**
@@ -392,6 +412,10 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.range_to_aria": "{feature}, up to",
   "search.facets.show_all": "Show all ({count})",
   "search.facets.show_less": "Show fewer",
+  "search.facets.search": "Find a filter",
+  "search.facets.search_empty": "No filter matches this",
+  "search.facets.match_count.one": "{count} listing matches",
+  "search.facets.match_count.other": "{count} listings match",
   "search.facets.range_invalid":
     "“From” is larger than “to”, so nothing could match. Swap them to apply this range.",
 
@@ -406,6 +430,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.filters.all": "All filters",
   "search.filters.short": "Filters",
   "search.filters.chip_more": ", +{count}",
+  "search.filters.chips_overflow": "More · {count}",
 
   "search.empty.exits_title": "Try widening the search",
   "search.empty.up_a_level": "Go up a level",

package/src/i18n/ru.ts

@@ -112,6 +112,12 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.range_to_aria": "{feature}, до",
   "search.facets.show_all": "Показать все ({count})",
   "search.facets.show_less": "Свернуть",
+  "search.facets.search": "Найти фильтр",
+  "search.facets.search_empty": "Среди фильтров такого нет",
+  "search.facets.match_count.one": "Найдено {count} объявление",
+  "search.facets.match_count.few": "Найдено {count} объявления",
+  "search.facets.match_count.many": "Найдено {count} объявлений",
+  "search.facets.match_count.other": "Найдено {count} объявления",
   "search.facets.range_invalid":
     "«От» больше, чем «до», — под такой диапазон ничего не подойдёт. Поменяйте значения местами.",
 
@@ -130,6 +136,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.filters.all": "Все фильтры",
   "search.filters.short": "Фильтры",
   "search.filters.chip_more": ", +{count}",
+  "search.filters.chips_overflow": "Ещё {count}",
 
   "search.empty.exits_title": "Попробуйте расширить поиск",
   "search.empty.up_a_level": "Подняться на уровень выше",

package/src/state/facets.ts

@@ -128,6 +128,25 @@ export interface FacetGroup {
   readonly selected: readonly string[];
 }
 
+/**
+ * How many candidate documents carry ANY value of this axis — the evidence
+ * that people actually fill this field in. Uncounted options are `null`
+ * (never `0` — different sentences) and contribute nothing, so a group the
+ * server did not count sums to zero.
+ *
+ * Two surfaces rank by it, for the same reason: the chip row orders its
+ * counted band by coverage (D16 reopen — an imported catalogue gave the
+ * phones leaf option tables for its wholesale plumbing, and schema order put
+ * them ahead of the brand), and the filter panel opens its top-coverage
+ * groups and collapses the rest (the 5717px rail). One definition, or the
+ * two surfaces drift into two opinions about which axes matter.
+ */
+export function facetCoverage(group: FacetGroup): number {
+  let total = 0;
+  for (const option of group.options) total += option.count ?? 0;
+  return total;
+}
+
 export interface BuildFacetGroupsInput {
   /** The envelope's `facets`: `{slug: {value: count}}`. */
   readonly facets: Readonly<Record<string, Readonly<Record<string, number>>>>;