@stapel/search-react 0.14.2 → 0.15.0

package/src/default/EmptyExits.tsx

@@ -0,0 +1,203 @@
+/**
+ * `<EmptyExits>` — the way out of a search that found nothing.
+ *
+ * ## What it replaces
+ *
+ * One sentence. "Nothing matches this search." — and then the page stopped:
+ * fifteen filter chips above it, a location the person never chose, and no
+ * control that widens anything. Measured on a live board where 2924
+ * leaves out of 2924 were empty, that sentence was the terminal state of the
+ * whole catalogue — and the two constraints most likely to have caused it (a
+ * 25 km radius the page applied on its own, and the narrowest segment of the
+ * category path) were exactly the two the person had never typed.
+ *
+ * ## The exits are derived, never invented
+ *
+ * Every button here is built out of state this pair already owns, and each
+ * one removes exactly one constraint:
+ *
+ *  - **up a level** — drop the last segment of `category=`. The pair holds
+ *    the path, so this needs no tree; what it cannot do is NAME the parent,
+ *    which is why the label is "the level above" and not a guess.
+ *  - **widen the radius** — multiply `geo.radiusKm`. Offered only when a
+ *    radius is actually applied, because widening a search that was never
+ *    narrowed is a button that changes nothing.
+ *  - **search everywhere** — drop the geo constraint entirely. The single
+ *    most likely culprit on this board: the SERP applied a default radius
+ *    the category page did not, so the same category read 2 from the API and
+ *    "0 listings, nothing found" on screen.
+ *  - **drop one filter** — one button per applied facet slug and per applied
+ *    range, labelled with the filter's own name. "The narrowest filter" is
+ *    not a thing this pair can rank, so it does not pretend to: it offers
+ *    every constraint separately and lets the person pick.
+ *  - **clear everything** — the existing `search.facets.clear_all`, last,
+ *    for the person who wants the catalogue back.
+ *
+ * ## Siblings come from the host
+ *
+ * "Show me the neighbouring sections, with their counts" is the exit a buyer
+ * most wants and the one this package must not build: walking the tree is
+ * `categories-react`'s job and the counts are the server's. So it is a SLOT
+ * (`renderExtra`), rendered above the derived exits — the host that already
+ * draws the category picker has the tree in hand, and a host that fills
+ * nothing still gets every exit above.
+ *
+ * ## Nothing to offer is a valid answer
+ *
+ * A bare, unfiltered, uncentred search that finds nothing has no exit to
+ * offer and this renders the sentence alone. A row of disabled buttons would
+ * be worse than the sentence.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import { useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { featureName } from "@stapel/attributes-react";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/**
+ * How much wider "widen the radius" makes it.
+ *
+ * Four, not two: doubling a 25 km radius covers four times the area and
+ * usually still nothing on a thin board, so the person taps the same button
+ * three times. Four times the radius is sixteen times the area — one tap
+ * that visibly changes the answer, which is what makes it an exit rather
+ * than a nudge.
+ */
+export const RADIUS_WIDEN_FACTOR = 4;
+
+export interface EmptyExitsProps {
+  /** The category schema, for naming an applied filter the way its chip does. */
+  readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * The host's own exits — sibling sections with their counts, most usefully.
+   * Rendered first, above the derived ones.
+   */
+  readonly renderExtra?: () => ReactNode;
+}
+
+/** One exit, resolved to its label and the state change it performs. */
+interface Exit {
+  readonly id: string;
+  readonly label: string;
+  readonly apply: () => void;
+}
+
+/** The parent of a `root/leaf` path, or `undefined` at the root. */
+export function parentCategory(category: string | undefined): string | undefined {
+  if (category === undefined) return undefined;
+  const parts = category.split("/").filter((part) => part.length > 0);
+  if (parts.length <= 1) return undefined;
+  return parts.slice(0, -1).join("/");
+}
+
+export function EmptyExits(props: EmptyExitsProps): ReactElement | null {
+  const t = useT();
+  const { state, setCategory, setGeo, setFilter, setRange, clearAll } =
+    useSearchState();
+
+  const bySlug = new Map<string, FeatureDef>();
+  for (const feature of props.categoryFeatures ?? []) bySlug.set(feature.slug, feature);
+  const nameOf = (slug: string): string => {
+    const feature = bySlug.get(slug);
+    return feature === undefined ? slug : t(featureName(feature));
+  };
+
+  const exits: Exit[] = [];
+
+  const parent = parentCategory(state.category);
+  if (parent !== undefined) {
+    exits.push({
+      id: "up",
+      label: t(SEARCH_I18N_KEYS.emptyUpALevel),
+      apply: () => {
+        setCategory(parent);
+      },
+    });
+  }
+
+  const geo = state.geo;
+  if (geo !== undefined && geo.kind === "center" && geo.radiusKm !== undefined) {
+    const wider = Math.round(geo.radiusKm * RADIUS_WIDEN_FACTOR);
+    exits.push({
+      id: "widen",
+      label: t(SEARCH_I18N_KEYS.emptyWidenRadius, { km: wider }),
+      apply: () => {
+        setGeo({ ...geo, radiusKm: wider });
+      },
+    });
+  }
+  if (geo !== undefined) {
+    exits.push({
+      id: "anywhere",
+      label: t(SEARCH_I18N_KEYS.emptyAnywhere),
+      apply: () => {
+        setGeo(null);
+      },
+    });
+  }
+
+  for (const slug of Object.keys(state.filters)) {
+    if ((state.filters[slug] ?? []).length === 0) continue;
+    exits.push({
+      id: `filter:${slug}`,
+      label: t(SEARCH_I18N_KEYS.emptyDropFilter, { name: nameOf(slug) }),
+      apply: () => {
+        setFilter(slug, []);
+      },
+    });
+  }
+  for (const slug of Object.keys(state.ranges)) {
+    exits.push({
+      id: `range:${slug}`,
+      label: t(SEARCH_I18N_KEYS.emptyDropFilter, { name: nameOf(slug) }),
+      apply: () => {
+        setRange(slug, null);
+      },
+    });
+  }
+
+  if (exits.length > 1) {
+    exits.push({
+      id: "clear",
+      label: t(SEARCH_I18N_KEYS.facetsClearAll, { count: exits.length }),
+      apply: clearAll,
+    });
+  }
+
+  const extra = props.renderExtra?.();
+  if (exits.length === 0 && extra === undefined) return null;
+
+  return (
+    <Flex
+      vertical
+      gap={spacing[3]}
+      data-testid="search-empty-exits"
+      style={{ marginBlockStart: spacing[4] }}
+    >
+      {extra}
+      {exits.length > 0 && (
+        <Flex vertical gap={spacing[2]}>
+          <Typography.Text type="secondary">
+            {t(SEARCH_I18N_KEYS.emptyExitsTitle)}
+          </Typography.Text>
+          <Flex wrap gap={spacing[2]}>
+            {exits.map((exit) => (
+              <Button
+                key={exit.id}
+                data-testid={`search-empty-exit-${exit.id}`}
+                data-analytics="none"
+                data-analytics-reason="widening a search is a read, not a flow step"
+                onClick={exit.apply}
+              >
+                {exit.label}
+              </Button>
+            ))}
+          </Flex>
+        </Flex>
+      )}
+    </Flex>
+  );
+}

package/src/default/FilterChips.tsx

@@ -87,6 +87,22 @@
  * counter ran out of plan slots at `MAX_FACET_FIELDS`, not that a person
  * cannot filter by it. `r.<slug>` still answers for a skipped slug.
  *
+ * ## The one case where band 3 IS deleted: a barren result
+ *
+ * There is exactly one piece of evidence strong enough, and the server sends
+ * it: the plan was counted (`facet_meta.counted`) over a candidate set of
+ * ZERO (`facet_meta.candidates`). Then every counted group is empty and drops
+ * out on its own, and the only chips left standing are the ones that never
+ * needed a count — the category's numeric attributes, drawn from the schema
+ * alone. Measured live on a cars leaf inside a 25 km radius that held no
+ * cars, that row read "Price / Colour / Availability / Steering side / Year / VIN or body
+ * number / Dealer offer "…" x9": the make and the model gone
+ * because they had nothing to count, a body number and nine dealer
+ * promotions in their place. An unapplied numeric axis over an empty set
+ * narrows nothing that is not already nothing; it states nothing and takes
+ * the room the empty state's exits need. APPLIED ones stay, always — a
+ * constraint keeps the control that removes it.
+ *
  * ## Why the CATEGORY leads the row
  *
  * The owner's navigation model puts levels 1-2 of the catalogue on tiles and
@@ -207,7 +223,8 @@ function specApplied(spec: ChipSpec): boolean {
  */
 export function orderChipFilters(
   ranges: readonly RangeGroup[],
-  facets: readonly FacetGroup[]
+  facets: readonly FacetGroup[],
+  options: { readonly barren?: boolean } = {}
 ): readonly ChipSpec[] {
   const specs: ChipSpec[] = [
     ...ranges.map(
@@ -217,7 +234,11 @@ export function orderChipFilters(
           : { band: "attribute_range", range }
     ),
     ...facets.map((facet): ChipSpec => ({ band: "facet", facet })),
-  ];
+  ].filter(
+    (spec) =>
+      !(options.barren === true && spec.band === "attribute_range") ||
+      specApplied(spec)
+  );
   return [...specs].sort((a, b) => {
     const applied = Number(specApplied(b)) - Number(specApplied(a));
     if (applied !== 0) return applied;
@@ -311,9 +332,17 @@ function chipLabel(group: FacetGroup, t: (key: string, p?: Record<string, unknow
  * URL genuinely carries, which is the line the geo chip draws too: never print
  * a coordinate, always print the name you actually have.
  */
-export function categoryLeaf(path: string): string {
+export function categoryLeaf(path: string): string | undefined {
   const parts = path.split("/").filter((part) => part.length > 0);
-  return parts[parts.length - 1] ?? path;
+  const leaf = parts[parts.length - 1];
+  if (leaf === undefined) return undefined;
+  // A path of database IDS has no readable last segment, and printing one
+  // puts a green pill reading «165» on the SERP — which is what the live
+  // board did, permanently, on every category page. An id is not a
+  // half-answer the way a slug is: it names nothing a person could have
+  // typed. When the leaf is a bare number the chip falls back to the
+  // FILTER's own name, the same thing every other unset chip shows.
+  return /^\d+$/.test(leaf) ? undefined : leaf;
 }
 
 export function FilterChips(props: FilterChipsProps): ReactElement | null {
@@ -392,9 +421,23 @@ export function FilterChips(props: FilterChipsProps): ReactElement | null {
   const categoryChipLabel: ReactNode =
     category === undefined
       ? t(SEARCH_I18N_KEYS.categoryTitle)
-      : (props.categoryLabel ?? categoryLeaf(category));
-
-  const ordered = orderChipFilters(ranges, groups);
+      : (props.categoryLabel ??
+        categoryLeaf(category) ??
+        t(SEARCH_I18N_KEYS.categoryTitle));
+
+  // The server counted a plan over a candidate set of ZERO. Every counted
+  // facet is therefore empty and drops out of `groups` above — and what is
+  // left standing is the band that never needed a count: the numeric
+  // attributes drawn from the category schema alone. On the live cars leaf
+  // that row read "Price / Colour / Availability / Steering side / Year /
+  // VIN / Dealer offer x9" — the make and the model gone, a body-number field
+  // and nine dealer promotions in their place, on a page with no cars on it.
+  // An unapplied attribute range on an empty result narrows nothing that is
+  // not already nothing, so it states nothing and takes the room the exits
+  // 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 geo = state.geo;
   const showGeoChip =

package/src/default/SearchPage.tsx

@@ -250,6 +250,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 +314,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;
@@ -415,6 +424,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 } : {})}
@@ -479,6 +491,10 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(props.degradationNotice !== undefined
         ? { degradationNotice: props.degradationNotice }
         : {})}
+      {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+      {...(props.renderEmptyExits !== undefined
+        ? { renderEmptyExits: props.renderEmptyExits }
+        : {})}
     />
   );
 

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/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}",