@stapel/search-react 0.14.2 → 0.16.0

package/src/default/SearchPage.tsx

@@ -197,6 +197,9 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * coordinate, with or without it.
    */
   readonly geoLabel?: ReactNode;
+  /** Print the engine's list of uncounted facet slugs in the filter panel.
+   * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
+  readonly skippedNotice?: boolean;
   /**
    * Open the search centred where the visitor is, when the URL says nothing
    * about location — see {@link SearchStateProviderProps.defaultGeo} for the
@@ -250,6 +253,14 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * not the viewport — not an escape hatch for "I prefer a column on phones".
    */
   readonly filtersLayout?: SearchFiltersLayout;
+  /**
+   * The host's own exits from an empty result — sibling sections with their
+   * counts. A SLOT for the same reason `breadcrumb` is one: walking the tree
+   * belongs to `categories-react`. Everything the pair can derive on its own
+   * (up a level, widen the radius, search everywhere, drop one filter) is
+   * offered whether this is filled or not — see {@link EmptyExits}.
+   */
+  readonly renderEmptyExits?: () => ReactNode;
   /**
    * Open the phone filter sheet on mount.
    *
@@ -306,6 +317,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
+  readonly renderEmptyExits?: () => ReactNode;
   readonly locale?: string;
   readonly resolveFacetLabels?: FacetLabelResolver;
   readonly searchBox?: boolean;
@@ -314,6 +326,7 @@ interface SearchPageBodyProps {
   readonly categoryLabel?: ReactNode;
   readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
   readonly geoLabel?: ReactNode;
+  readonly skippedNotice?: boolean;
   readonly footer?: ReactNode;
   readonly filtersHeader?: ReactNode;
   readonly resultsHeader?: ReactNode;
@@ -415,6 +428,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         <FacetPanelPane
           {...(layout === "sheet" ? { heading: null } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+          {...(props.renderEmptyExits !== undefined
+            ? { renderEmptyExits: props.renderEmptyExits }
+            : {})}
           {...(locale !== undefined ? { locale } : {})}
           {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(props.languages !== undefined ? { languages: props.languages } : {})}
@@ -425,6 +441,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             ? { renderGeoFilter: props.renderGeoFilter }
             : {})}
           {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+          {...(props.skippedNotice !== undefined
+            ? { skippedNotice: props.skippedNotice }
+            : {})}
         />
       )}
     </Flex>
@@ -479,6 +498,10 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(props.degradationNotice !== undefined
         ? { degradationNotice: props.degradationNotice }
         : {})}
+      {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+      {...(props.renderEmptyExits !== undefined
+        ? { renderEmptyExits: props.renderEmptyExits }
+        : {})}
     />
   );
 
@@ -595,6 +618,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     categoryLabel,
     renderGeoFilter,
     geoLabel,
+    skippedNotice,
     defaultGeo,
     footer,
     filtersHeader,
@@ -628,6 +652,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(categoryLabel !== undefined ? { categoryLabel } : {})}
           {...(renderGeoFilter !== undefined ? { renderGeoFilter } : {})}
           {...(geoLabel !== undefined ? { geoLabel } : {})}
+          {...(skippedNotice !== undefined ? { skippedNotice } : {})}
           {...(footer !== undefined ? { footer } : {})}
           {...(filtersHeader !== undefined ? { filtersHeader } : {})}
           {...(resultsHeader !== undefined ? { resultsHeader } : {})}

package/src/default/SearchResultsPane.tsx

@@ -36,6 +36,7 @@ import {
   visuallyHidden,
 } from "@stapel/tokens-antd/skin";
 import { spacing } from "@stapel/tokens";
+import type { FeatureDef } from "@stapel/attributes-react";
 import type { SearchItem } from "../api/types.js";
 import { SearchResults } from "../headless/SearchResults.js";
 import type { SearchResultsBag } from "../headless/SearchResults.js";
@@ -43,6 +44,7 @@ import { useScorerNames } from "../headless/useScorerNames.js";
 import { SEARCH_WINDOW_EXCEEDED } from "../i18n/errorsMap.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { DegradationNotice } from "./DegradationNotice.js";
+import { EmptyExits } from "./EmptyExits.js";
 import type { DegradationNoticeVariant } from "./DegradationNotice.js";
 import { SearchResultCard } from "./SearchResultCard.js";
 import type { SearchCardRenderer } from "./SearchResultCard.js";
@@ -191,6 +193,20 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * viewport is not spent saying "Results" over a list of results.
    */
   readonly header?: "banner" | "compact";
+  /**
+   * The category's feature schema, used ONLY to name an applied filter in the
+   * empty state's exits ("Without Brand" rather than "Without vendor").
+   * Absent, an exit falls back to the slug, which is still a removable
+   * constraint the person can read.
+   */
+  readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * The host's own exits from an empty result — sibling sections with their
+   * counts, most usefully. Rendered above the derived exits (see
+   * {@link EmptyExits}); walking the tree is `categories-react`'s job, so
+   * this pair offers the slot and never the tree.
+   */
+  readonly renderEmptyExits?: () => ReactNode;
 }
 
 function Count(props: { bag: SearchResultsBag }): ReactElement | null {
@@ -311,10 +327,23 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
               skeletonRows={6}
               onRetry={bag.refetch}
               empty={
-                <EmptyState
-                  title={t(SEARCH_I18N_KEYS.resultsEmpty)}
-                  testId="search-empty"
-                />
+                <>
+                  <EmptyState
+                    title={t(SEARCH_I18N_KEYS.resultsEmpty)}
+                    testId="search-empty"
+                  />
+                  {/* The sentence alone was the terminal state of a whole
+                      catalogue. Every exit here removes exactly one
+                      constraint the person did not necessarily choose. */}
+                  <EmptyExits
+                    {...(props.categoryFeatures !== undefined
+                      ? { categoryFeatures: props.categoryFeatures }
+                      : {})}
+                    {...(props.renderEmptyExits !== undefined
+                      ? { renderExtra: props.renderEmptyExits }
+                      : {})}
+                  />
+                </>
               }
               failed={(error) => {
                 // The window refusal is a DIFFERENT sentence from a failed

package/src/default/index.ts

@@ -58,6 +58,8 @@ export {
   orderChipFilters,
 } from "./FilterChips.js";
 export type { ChipBand, ChipSpec, FilterChipsProps } from "./FilterChips.js";
+export { EmptyExits, RADIUS_WIDEN_FACTOR, parentCategory } from "./EmptyExits.js";
+export type { EmptyExitsProps } from "./EmptyExits.js";
 
 export { LocationSummaryLine } from "./LocationSummaryLine.js";
 export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";

package/src/headless/FacetPanel.tsx

@@ -65,6 +65,7 @@ const EMPTY_META: FacetMeta = {
   candidates: 0,
   counted: [],
   skipped: [],
+  dropped_filters: [],
   core_ranges: [],
 };
 

package/src/headless/useSearchBox.ts

@@ -173,24 +173,30 @@ function degradedWith(answer: SuggestAnswer | undefined, literal: string): boole
 /**
  * The destinations worth offering out of one answer.
  *
- * A category with a count of `0` is a section with nothing in it: following it
- * lands the buyer on an empty SERP, which is a dead end dressed as a
- * destination — and the server does return those (it reads the count with a
- * `0` default and ranks them last), so somebody has to drop them.
+ * **Every category the server ranked, in the order it ranked them.** Until
+ * 0.15 this dropped every row whose count was `0`, on the reasoning that an
+ * empty section is a dead end dressed as a destination. That reasoning holds
+ * for a stocked board and inverts on a young one, which is what the live
+ * measurement showed: 3036 leaves, ~100 listings, so 2924 leaves read zero
+ * and the filter deleted the answer. Typing a word with six real sections behind it in
+ * the catalogue produced NO PANEL AT ALL, and so did two other everyday
+ * words; the type-ahead told a buyer those sections do not exist, about
+ * sections that do. A catalogue you cannot navigate until somebody stocks it
+ * is worse than one that admits a section is empty.
  *
- * The one exception is `category_rollup`, where EVERY count is `0` because the
- * ancestry never arrived rather than because the sections are empty. Filtering
- * on the count there would delete the whole group for a reason that has
- * nothing to do with what is in the catalogue, so the rows are kept and the
- * numbers are what the surface omits.
+ * The server already ranks stocked sections above empty ones
+ * (`stapel-search` 0.8: stock, then match quality, then count) so the useful
+ * rows still come first, and every row carries its own `count` for the
+ * surface to print honestly — "0 listings" is a fact a person can act on,
+ * an absent panel is not. Nothing is dropped here; a surface that wants a
+ * shorter list slices it.
  */
 export function offerableCategories(
   answer: SuggestAnswer | undefined
 ): readonly SuggestCategory[] {
   const categories = answer?.categories;
   if (categories === undefined || categories.length === 0) return NO_CATEGORIES;
-  if (degradedWith(answer, SUGGEST_DEGRADED_ROLLUP)) return categories;
-  return categories.filter((category) => category.count > 0);
+  return categories;
 }
 
 export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {

package/src/i18n/es.ts

@@ -102,6 +102,11 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.filters.short": "Filtros",
   "search.filters.chip_more": ", +{count}",
 
+  "search.empty.exits_title": "Prueba a ampliar la búsqueda",
+  "search.empty.up_a_level": "Subir un nivel",
+  "search.empty.widen_radius": "Buscar en un radio de {km} km",
+  "search.empty.anywhere": "Buscar en todas partes",
+  "search.empty.drop_filter": "Sin «{name}»",
   "search.category.title": "Categoría",
   "search.category.clear": "Buscar en todo el catálogo",
   "search.category.current": "Buscando dentro de {path}",

package/src/i18n/keys.ts

@@ -162,6 +162,23 @@ export const SEARCH_I18N_KEYS = {
    * family — nothing is being counted in words. */
   filtersChipMore: "search.filters.chip_more",
 
+  // ── 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. */
+  emptyExitsTitle: "search.empty.exits_title",
+  /** Drop the last segment of the category path. Deliberately unnamed: the
+   * pair holds a path of slugs or ids and cannot name the parent, and a
+   * guessed name on a navigation control is worse than an honest direction. */
+  emptyUpALevel: "search.empty.up_a_level",
+  /** "Search within {km} km" — the widened radius, already multiplied. */
+  emptyWidenRadius: "search.empty.widen_radius",
+  /** Drop the location constraint. Distinct from `search.geo.clear`, which
+   * labels the same action inside the location picker: here it is one exit
+   * among several and has to name the constraint it removes. */
+  emptyAnywhere: "search.empty.anywhere",
+  /** "Without {name}" — one applied filter, named as its own chip names it. */
+  emptyDropFilter: "search.empty.drop_filter",
+
   // ── category (a host slot, plus the control that removes it) ─────────────
   categoryTitle: "search.category.title",
   categoryClear: "search.category.clear",
@@ -390,6 +407,11 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.filters.short": "Filters",
   "search.filters.chip_more": ", +{count}",
 
+  "search.empty.exits_title": "Try widening the search",
+  "search.empty.up_a_level": "Go up a level",
+  "search.empty.widen_radius": "Search within {km} km",
+  "search.empty.anywhere": "Search anywhere",
+  "search.empty.drop_filter": "Without {name}",
   "search.category.title": "Category",
   "search.category.clear": "Search the whole catalogue",
   "search.category.current": "Searching inside {path}",

package/src/i18n/ru.ts

@@ -131,6 +131,11 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.filters.short": "Фильтры",
   "search.filters.chip_more": ", +{count}",
 
+  "search.empty.exits_title": "Попробуйте расширить поиск",
+  "search.empty.up_a_level": "Подняться на уровень выше",
+  "search.empty.widen_radius": "Искать в радиусе {km} км",
+  "search.empty.anywhere": "Искать везде",
+  "search.empty.drop_filter": "Без «{name}»",
   "search.category.title": "Категория",
   "search.category.clear": "Искать по всему каталогу",
   "search.category.current": "Ищем внутри {path}",

package/src/state/facets.ts

@@ -31,7 +31,11 @@
  * A slug the server SKIPPED (`facet_meta.skipped`, dropped at
  * `MAX_FACET_FIELDS`) is not counted at all. Its options carry `count: null`,
  * never `0` — "we did not count this" and "there are none" are different
- * sentences and the honest one has to survive to the screen.
+ * sentences and the honest one has to survive to the screen. Its options come
+ * from the CATEGORY SCHEMA, because a count is not a licence to filter: the
+ * server accepts `f.<slug>` whether or not it counted it, so an uncounted
+ * facet is a filter that exists and a number that is missing, not a filter
+ * that does not exist. See {@link buildFacetGroups}.
  *
  * 3. **Not every counted slug is a FILTER.** The plan is built from the leaf
  *    category's feature defs and the counter counts whatever is indexed, so a
@@ -352,13 +356,37 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
     const push = (value: string): void => {
       if (!values.includes(value)) values.push(value);
     };
-    // Declared order first (closed sets), then whatever else the counter
-    // returned, then anything selected that neither of them mentioned.
-    for (const value of declared) if (value in counts) push(value);
-    const remaining = Object.keys(counts)
-      .filter((value) => !declared.includes(value))
-      .sort((a, b) => (counts[b] ?? 0) - (counts[a] ?? 0) || a.localeCompare(b));
-    for (const value of remaining) push(value);
+    if (counted) {
+      // Declared order first (closed sets), then whatever else the counter
+      // returned, then anything selected that neither of them mentioned.
+      for (const value of declared) if (value in counts) push(value);
+      const remaining = Object.keys(counts)
+        .filter((value) => !declared.includes(value))
+        .sort((a, b) => (counts[b] ?? 0) - (counts[a] ?? 0) || a.localeCompare(b));
+      for (const value of remaining) push(value);
+    } else {
+      // A COUNT IS NOT A LICENCE TO FILTER.
+      //
+      // `counts` is empty here by definition — the counter never looked at
+      // this slug (`facet_meta.skipped`, the plan overrunning
+      // `MAX_FACET_FIELDS`) or the deployment counts nothing at all. Gating
+      // the options on `value in counts` therefore left the facet with NONE,
+      // and a group with no options is dropped by every surface that draws
+      // one. Measured on a live cars leaf: 26 facetable features declared, 12
+      // counted, 14 rendered as a warning naming filters the person could not
+      // then use — while `/query` accepts `f.<slug>` for every one of them.
+      //
+      // So an uncounted facet is built from the SCHEMA: the option table the
+      // category config already carries (`config.options`), or the captions
+      // the answer sent for it. The counts stay `null` below — "nobody
+      // counted this" is still said, in the place it belongs (beside the
+      // option), and it no longer decides whether the filter exists.
+      //
+      // A `ref_select` whose config is a bare `optionsRef` pointer has no
+      // table here and no options to draw; naming that gap is
+      // `MODULE.md`'s job, inventing values would not be.
+      for (const value of declared) push(value);
+    }
     for (const value of selected) push(value);
 
     const labelOptions = {