@stapel/search-react 0.9.1 → 0.11.0

package/src/default/SearchPage.tsx

@@ -12,9 +12,9 @@
  * The seams a storefront fills: `renderCard` (a `<ListingCard>`),
  * `categoryFeatures` (from categories-react, for facet labels and range rows),
  * `renderCategoryFilter` / `renderGeoFilter` (controls other pairs own),
- * `footer` (the container's own chrome), `filtersHeader` and `resultsHeading`.
- * None of them is optional behaviour in disguise — every one has a working
- * default or a visible placeholder.
+ * `footer` (the container's own chrome), `filtersHeader`, `resultsHeader` and
+ * `resultsHeading`. None of them is optional behaviour in disguise — every one
+ * has a working default or a visible placeholder.
  *
  * ── The screen could not start a search ───────────────────────────────────
  *
@@ -185,6 +185,25 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * sense that matters and not a decoration bolted on top.
    */
   readonly filtersHeader?: ReactNode;
+  /**
+   * The row ABOVE the chips and the results — where `<LocationSummaryLine>`
+   * goes on the phone SERP.
+   *
+   * A NEW slot rather than a reuse, and the existing four were each checked
+   * first: `filtersHeader` is inside the filter panel (it is a filter, and on
+   * a phone it is behind the sheet, which is precisely where a location
+   * summary must NOT be); `breadcrumb` renders in the right place but names a
+   * walk up the CATEGORY tree, and a host wanting a trail AND a location row
+   * would have to choose; `resultsHeading` and the pane's `toolbar` are inside
+   * the results pane, below the chips. Nothing sat between "the search box"
+   * and "the filters", and that gap is exactly the ref's location row.
+   *
+   * It is rendered in the page's vertical stack, so it spans the full width in
+   * BOTH layouts — above the chip row on a phone, above the two columns on a
+   * desktop. That is deliberate: whatever states where a search is looking
+   * describes the whole page, not the results column of it.
+   */
+  readonly resultsHeader?: ReactNode;
   /** What this surface calls its result list. See
    * {@link SearchResultsPaneProps.heading}. */
   readonly resultsHeading?: ReactNode;
@@ -261,6 +280,7 @@ interface SearchPageBodyProps {
   readonly geoLabel?: ReactNode;
   readonly footer?: ReactNode;
   readonly filtersHeader?: ReactNode;
+  readonly resultsHeader?: ReactNode;
   readonly resultsHeading?: ReactNode;
   readonly degradationNotice?: DegradationNoticeVariant;
   readonly filtersLayout?: SearchFiltersLayout;
@@ -414,6 +434,14 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       )}
       <UrlIssueNotice />
 
+      {/* Above the chips in the sheet layout and above the columns in the
+          other one — see {@link SearchPageProps.resultsHeader}. `?? null` is
+          the written decision, not an oversight: a page with nothing to say
+          about location says nothing rather than reserving a blank row. */}
+      {props.resultsHeader !== undefined && (
+        <div data-testid="search-results-header">{props.resultsHeader}</div>
+      )}
+
       {showFilters && layout === "sheet" ? (
         <>
           {/* The phone's filter row. It REPLACES the full-width "Filters (3)"
@@ -492,6 +520,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     defaultGeo,
     footer,
     filtersHeader,
+    resultsHeader,
     resultsHeading,
     degradationNotice,
     filtersLayout,
@@ -521,6 +550,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(geoLabel !== undefined ? { geoLabel } : {})}
           {...(footer !== undefined ? { footer } : {})}
           {...(filtersHeader !== undefined ? { filtersHeader } : {})}
+          {...(resultsHeader !== undefined ? { resultsHeader } : {})}
           {...(resultsHeading !== undefined ? { resultsHeading } : {})}
           {...(degradationNotice !== undefined ? { degradationNotice } : {})}
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}

package/src/default/geoSheet.tsx

@@ -0,0 +1,161 @@
+/**
+ * The LOCATION sheet — one implementation, two doors.
+ *
+ * `<FilterChips>`'s geo chip opened it and `<LocationSummaryLine>` opens it
+ * too: on the ref's SERP both controls say where the search is centred, one
+ * on the summary row and one in the chip strip, and a person tapping either
+ * must land in the same place. Two copies of a bottom sheet is two places for
+ * "clear the location" to behave differently, so the sheet is a component and
+ * the two surfaces are two `open` flags on it.
+ *
+ * ── What the sheet can do without a geocoder, and what it cannot ───────────
+ *
+ * SETTING a centre needs a map and a place-name lookup, which belong to
+ * `geo-react` and to the deployment: that is `renderGeoFilter`, and when it is
+ * unfilled the gap is NAMED (`SlotPlaceholder`) rather than left as a blank
+ * area under the sheet's title. ADJUSTING or CLEARING a location the URL
+ * already carries needs neither — `lat`/`lon`/`radius_km` are numbers this
+ * pair owns — which is why the sheet still opens usefully on a shared link
+ * with no slot wired.
+ *
+ * NAMING the place is a third thing and it is the host's: this package holds
+ * two coordinates and has no way to turn them into "Berlin Mitte", so it
+ * prints the name it was handed (`geoLabel`) or says that a place is chosen —
+ * never the numbers. `test/geo.test.tsx` asserts no digit of the point reaches
+ * the DOM, on either surface.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import { SkinDialog } from "@stapel/tokens-antd/skin";
+import { SlotPlaceholder, useT, useTPlural } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { useAppliedCount } from "../headless/useAppliedCount.js";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { geoSummaryFallback } from "./FacetPanelPane.js";
+import type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+
+/** The test ids a surface gives its own copy of the sheet — the chip row and
+ * the summary line each keep the names their tests already know. */
+export interface GeoSheetTestIds {
+  readonly sheet: string;
+  readonly apply: string;
+  readonly slot: string;
+  readonly summary: string;
+  readonly clear: string;
+}
+
+/** The chip row's door. These names predate the split and are what
+ * `test/geo.test.tsx` already asks for, so they travel with the sheet rather
+ * than being renamed by a refactor nobody asked to observe. */
+export const CHIP_GEO_TEST_IDS: GeoSheetTestIds = {
+  sheet: "filter-chip-sheet-geo",
+  apply: "filter-chip-apply-geo",
+  slot: "search-chip-geo-slot",
+  summary: "search-chip-geo-summary",
+  clear: "search-chip-geo-clear",
+};
+
+/** The summary line's door — a different set, so a page holding both rows
+ * never hands a test two elements under one name. */
+export const SUMMARY_GEO_TEST_IDS: GeoSheetTestIds = {
+  sheet: "search-location-sheet",
+  apply: "search-location-apply",
+  slot: "search-location-slot",
+  summary: "search-location-sheet-summary",
+  clear: "search-location-clear",
+};
+
+export interface GeoSheetProps {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
+  readonly geoLabel?: ReactNode;
+  readonly testIds: GeoSheetTestIds;
+}
+
+/**
+ * "Show 25 results", not "Show results".
+ *
+ * The results are BEHIND this sheet, so the button that closes it is the only
+ * place a person learns what their choice did. When the engine cannot say how
+ * many there are it says nothing rather than a number it made up.
+ */
+export function useApplyLabel(): string {
+  const t = useT();
+  const tPlural = useTPlural();
+  const applied = useAppliedCount();
+  return applied.count === null || applied.kind === "unknown"
+    ? t(SEARCH_I18N_KEYS.filtersApply)
+    : tPlural(
+        applied.kind === "at_least"
+          ? SEARCH_I18N_KEYS.filtersShowCountAtLeast
+          : SEARCH_I18N_KEYS.filtersShowCount,
+        { count: applied.count }
+      );
+}
+
+export function GeoSheet(props: GeoSheetProps): ReactElement {
+  const t = useT();
+  const { state, setGeo } = useSearchState();
+  const applyLabel = useApplyLabel();
+  const geo = state.geo;
+  const summary: ReactNode =
+    geo === undefined
+      ? null
+      : (props.geoLabel ?? geoSummaryFallback(geo, t));
+
+  return (
+    <SkinDialog
+      open={props.open}
+      onClose={props.onClose}
+      title={t(SEARCH_I18N_KEYS.geoTitle)}
+      dismissLabel={t(SEARCH_I18N_KEYS.filtersDismiss)}
+      data-testid={props.testIds.sheet}
+      footer={
+        <Button
+          block
+          type="primary"
+          data-testid={props.testIds.apply}
+          data-analytics="none"
+          data-analytics-reason="the filter is already applied; this closes the sheet"
+          onClick={props.onClose}
+        >
+          {applyLabel}
+        </Button>
+      }
+    >
+      <Flex vertical gap={spacing[3]}>
+        {props.renderGeoFilter?.({
+          value: geo,
+          onChange: (next) => {
+            setGeo(next);
+          },
+        }) ?? (
+          <SlotPlaceholder
+            name="renderGeoFilter"
+            data-testid={props.testIds.slot}
+          />
+        )}
+        {geo !== undefined && (
+          <>
+            <Typography.Text type="secondary" data-testid={props.testIds.summary}>
+              {summary}
+            </Typography.Text>
+            <Button
+              style={{ alignSelf: "flex-start" }}
+              data-testid={props.testIds.clear}
+              data-analytics="none"
+              data-analytics-reason="a filter is a read, not a flow step"
+              onClick={() => {
+                setGeo(null);
+              }}
+            >
+              {t(SEARCH_I18N_KEYS.geoClear)}
+            </Button>
+          </>
+        )}
+      </Flex>
+    </SkinDialog>
+  );
+}

package/src/default/index.ts

@@ -51,6 +51,9 @@ export type {
 export { FilterChips, CHIP_ROW_CLASS, CHIP_ROW_STYLE_HREF, chipRowCss } from "./FilterChips.js";
 export type { FilterChipsProps } from "./FilterChips.js";
 
+export { LocationSummaryLine } from "./LocationSummaryLine.js";
+export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";
+
 export {
   FacetGroupControl,
   facetGroupShape,

package/src/headless/FacetPanel.tsx

@@ -31,6 +31,22 @@ export interface FacetPanelBag {
   readonly skipped: readonly string[];
   /** Slugs that WERE counted. */
   readonly counted: readonly string[];
+  /**
+   * Range slugs the server declared as CORE document columns
+   * (`facet_meta.core_ranges`, stapel-search 0.4.0+) — `price` on a
+   * classified board. They are not part of the category plan and are not
+   * counted; they are axes the panel may offer unconditionally, and they
+   * come from the answer so that a panel never draws a control over a
+   * filter the deployed server would answer zero for.
+   */
+  readonly coreRanges: readonly string[];
+  /**
+   * ISO 4217 code of the corpus, read off the first card of the answer, so
+   * a money range reads as money without the host wiring anything. The
+   * cards already carry it — `SearchResultCard` formats prices from the
+   * same field.
+   */
+  readonly currency: string | undefined;
   /** Size of the largest counted set — the number `approximate` is about. */
   readonly candidates: number;
   /** Facet values + ranges + geo currently applied. */
@@ -47,6 +63,7 @@ const EMPTY_META: FacetMeta = {
   candidates: 0,
   counted: [],
   skipped: [],
+  core_ranges: [],
 };
 
 /**
@@ -115,6 +132,7 @@ export function useFacetPanel(props: {
     buildFacetGroups({
       facets: data.facets,
       meta: data.facet_meta,
+      facetLabels: data.facet_labels,
       state: searchState,
       ...(props.categoryFeatures !== undefined
         ? { categoryFeatures: props.categoryFeatures }
@@ -129,6 +147,12 @@ export function useFacetPanel(props: {
     approximate: meta.approximate,
     skipped: meta.skipped,
     counted: meta.counted,
+    coreRanges: meta.core_ranges ?? [],
+    currency:
+      envelope.status === "ready"
+        ? envelope.data.items.find((item) => typeof item.card?.["currency"] === "string")
+            ?.card?.["currency"] as string | undefined
+        : undefined,
     candidates: meta.candidates,
     activeFilters,
     toggle: toggleFilter,

package/src/headless/useSearchCount.ts

@@ -0,0 +1,189 @@
+/**
+ * `useSearchCount(state)` — how many results a search state WOULD return,
+ * without showing any of them.
+ *
+ * A quick-search panel's button ("Show 128 listings") has to know the total
+ * for a state that is not on screen and not in the URL: the person is still
+ * composing it. `<SearchResults>` cannot answer that — it reads the committed
+ * URL state — and `useAppliedCount` deliberately reads the page already in
+ * cache. So this is a read of its own, over a state the caller hands in.
+ *
+ * ── THE GAP THIS HOOK RIDES OVER, STATED ──────────────────────────────────
+ *
+ * **stapel-search has no count-only endpoint.** `SearchApi` is `query`,
+ * `suggest` and `ranking`; nothing answers "how many" without also assembling
+ * a page. So this hook issues the ORDINARY query with the smallest page the
+ * endpoint will serve ({@link SEARCH_COUNT_PAGE_SIZE}) and facet counting
+ * switched off, and reads `count` out of the envelope it gets back. That is a
+ * deliberate choice with a cost: the engine still ranks the candidate set and
+ * the backend still serializes one row, so a count is roughly as expensive as
+ * a search. It is not a bug to be worked around client-side — a debounce is
+ * the mitigation, not a fix.
+ *
+ * FOLLOW-UP (stapel-search): a `GET /count` verb that answers the envelope's
+ * three count fields (`count`, `count_is_lower_bound`, `exact_total`) plus
+ * `degraded[]` and nothing else. When it lands, this hook's body changes and
+ * its signature does not.
+ *
+ * ── What it asks, and what it deliberately does not ───────────────────────
+ *
+ * The state is normalized before it goes out, and each removal is a rule:
+ *
+ *  - `facets: "off"` — a count does not draw a facet panel, and counting
+ *    facets is the expensive half of the request.
+ *  - `limit: 1` — the smallest page. Zero is not a page size the endpoint
+ *    documents, and asking for the default 24 would serialize 24 cards nobody
+ *    renders.
+ *  - `anchor` / `direction` dropped — a cursor asks about a PAGE, and the
+ *    count is about the whole result set. Keeping one would also cache the
+ *    same total once per page a person walked through.
+ *  - `sort` dropped — the total does not depend on the order, and keeping it
+ *    would miss the cache every time somebody changed the sort.
+ *
+ * Everything else — `q`, `category`, `owner`, filters, ranges, geo, `lang` —
+ * is exactly what a real search would carry, because those are what change the
+ * answer.
+ *
+ * ── The count is a LoadState, and the number is not always a number ────────
+ *
+ * The ready value carries `countKind`: `"exact"` is a total, `"at_least"` is
+ * a floor, `"unknown"` is the engine declining to say — and `count: null`
+ * under `"unknown"` is never `0`. A skin that renders the floor as a total is
+ * the defect `state/degradations.ts` exists to prevent, so the kind travels
+ * with the number rather than beside it.
+ */
+import { useEffect, useRef, useState } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import { searchQueryParams } from "../api/searchApi.js";
+import type { SearchQueryState } from "../api/types.js";
+import { useSearchQuery } from "../model/queries.js";
+import {
+  SEARCH_COUNT_DEBOUNCE_MS,
+  SEARCH_COUNT_PAGE_SIZE,
+} from "../state/limits.js";
+import { countKind, parseDegradations } from "../state/degradations.js";
+import type { SearchCountKind } from "../state/degradations.js";
+
+/** What a count read answers. */
+export interface SearchCount {
+  /** `null` is "the engine cannot say" — a real state, and NOT zero. */
+  readonly count: number | null;
+  /** Whether that number may be spoken as a total, as a floor, or at all. */
+  readonly kind: SearchCountKind;
+}
+
+/**
+ * The state a count is asked about: a doc type plus as much or as little of a
+ * search as the caller has composed. Partial on purpose — a panel holding one
+ * chosen facet is a legitimate question, and making it build a full
+ * {@link SearchQueryState} would mean spelling `filters: {}` and `ranges: {}`
+ * at every call site.
+ */
+export type SearchCountState = Pick<SearchQueryState, "type"> &
+  Partial<Omit<SearchQueryState, "type">>;
+
+export interface UseSearchCountOptions {
+  /**
+   * Ask at all. Default `true`. `false` holds the hook at `loading` (the
+   * fleet's shape for "no answer yet"), so a panel that is still resolving its
+   * category does not ask about a state it has not finished building.
+   */
+  readonly enabled?: boolean;
+  /**
+   * Quiet time before a CHANGED state is asked about (default
+   * {@link SEARCH_COUNT_DEBOUNCE_MS}). The first state is asked about
+   * immediately — a panel that opens should not wait a quarter second to say
+   * its number — and every change after that is coalesced, because a count
+   * rides the full query (see this file's header) and a request per keystroke
+   * is how a throttled endpoint starts answering 429.
+   *
+   * `0` disables it, for a caller whose state only changes on a commit.
+   */
+  readonly debounceMs?: number;
+}
+
+/**
+ * The wire form of a count question — exported so a test (or a host building
+ * its own key) can see exactly what is asked, rather than inferring it.
+ */
+export function countQueryState(state: SearchCountState): SearchQueryState {
+  const {
+    anchor: _anchor,
+    direction: _direction,
+    sort: _sort,
+    ...rest
+  } = state;
+  return {
+    q: "",
+    filters: {},
+    ranges: {},
+    ...rest,
+    facets: "off",
+    limit: SEARCH_COUNT_PAGE_SIZE,
+  };
+}
+
+/**
+ * A stable string for "is this the same question". Built from the same wire
+ * object the query key is built from, with the keys sorted, so two states
+ * assembled in a different order are one question and not two.
+ */
+function questionOf(state: SearchQueryState): string {
+  const params = searchQueryParams(state);
+  return JSON.stringify(
+    Object.entries(params).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+export function useSearchCount(
+  state: SearchCountState,
+  options: UseSearchCountOptions = {}
+): LoadState<SearchCount> {
+  const target = countQueryState(state);
+  const question = questionOf(target);
+  const debounceMs = options.debounceMs ?? SEARCH_COUNT_DEBOUNCE_MS;
+
+  // The state the timer will settle ON when it fires — always the newest one,
+  // not the one that started the timer. Typing "hond" then "honda" must ask
+  // about "honda" once, never about "hond" late.
+  const latest = useRef(target);
+  latest.current = target;
+
+  const [settled, setSettled] = useState<{
+    readonly question: string;
+    readonly state: SearchQueryState;
+  }>(() => ({ question, state: target }));
+
+  useEffect(() => {
+    if (settled.question === question) return undefined;
+    if (debounceMs <= 0) {
+      setSettled({ question, state: latest.current });
+      return undefined;
+    }
+    const handle = setTimeout(() => {
+      setSettled({ question, state: latest.current });
+    }, debounceMs);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [question, settled.question, debounceMs]);
+
+  // `useSearchQuery` keeps the previous answer on screen while the next one is
+  // in flight (`keepPreviousData`), which is what a counted button wants: the
+  // number belongs to the last state we actually asked about, and it does not
+  // blank between two of them.
+  const query = useSearchQuery(settled.state, {
+    enabled: options.enabled ?? true,
+  });
+
+  return mapLoad(loadStateFromQuery(query), (data) => ({
+    count: data.count,
+    kind: countKind(
+      data.count,
+      data.count_is_lower_bound,
+      data.exact_total,
+      parseDegradations(data.degraded)
+    ),
+  }));
+}

package/src/i18n/es.ts

@@ -72,6 +72,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "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.",
+  "search.range.price": "Precio",
   "search.facets.range_from": "Desde",
   "search.facets.range_to": "Hasta",
   "search.facets.range_apply": "Aplicar",
@@ -109,6 +110,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.geo.radius_km": "A menos de {km} km",
   "search.geo.radius_label": "Radio, km",
   "search.geo.clear": "En cualquier lugar",
+  "search.geo.everywhere": "Buscando en todas partes",
   "search.geo.box": "Dentro del área mostrada",
   "search.geo.chosen_place": "Un lugar elegido en el mapa",
 

package/src/i18n/keys.ts

@@ -103,6 +103,9 @@ export const SEARCH_I18N_KEYS = {
   facetsRangeToAria: "search.facets.range_to_aria",
   /** The reason "Apply" is off: the range reads backwards. */
   facetsRangeInvalid: "search.facets.range_invalid",
+  /** A CORE range axis has no FeatureDef and so no `name` to translate.
+   * `search.range.<slug>`; `price` is the one stapel-search ships. */
+  rangePrice: "search.range.price",
   /** The fold on a long facet group: "Show all (46)". The number is in
    * brackets and not a counted noun, so this is one message and not a plural
    * family — "(1)" never renders, because a group is only folded when the
@@ -151,6 +154,16 @@ export const SEARCH_I18N_KEYS = {
   geoRadiusKm: "search.geo.radius_km",
   geoRadiusLabel: "search.geo.radius_label",
   geoClear: "search.geo.clear",
+  /**
+   * What `<LocationSummaryLine>` says when NO location is applied.
+   *
+   * Not `search.geo.clear` reused: that is the label on a BUTTON that widens
+   * the search ("Anywhere"), and this is a STATEMENT about where the search is
+   * currently looking. The two are the same word in English and diverge the
+   * moment a translator treats one as an imperative — which is exactly the
+   * class of bug a shared key produces and nobody sees in the source locale.
+   */
+  geoEverywhere: "search.geo.everywhere",
   geoBox: "search.geo.box",
   /**
    * What a location constraint is called when nobody has given it a NAME.
@@ -289,6 +302,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "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.",
+  "search.range.price": "Price",
   "search.facets.range_from": "From",
   "search.facets.range_to": "To",
   "search.facets.range_apply": "Apply",
@@ -326,6 +340,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.geo.radius_km": "Within {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",
 

package/src/i18n/ru.ts

@@ -95,6 +95,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.not_counted": "не посчитано",
   "search.facets.drill_down_hint":
     "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",
+  "search.range.price": "Цена",
   "search.facets.range_from": "От",
   "search.facets.range_to": "До",
   "search.facets.range_apply": "Применить",
@@ -136,6 +137,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.geo.radius_km": "В радиусе {km} км",
   "search.geo.radius_label": "Радиус, км",
   "search.geo.clear": "Везде",
+  "search.geo.everywhere": "Ищем везде",
   "search.geo.box": "В показанной области",
   "search.geo.chosen_place": "Выбранное место на карте",
 

package/src/index.ts

@@ -89,11 +89,16 @@ export type {
 export {
   countIsEstimate,
   countKind,
+  degradationAudience,
   degradationMessageKey,
   isCountNuanceOnly,
   parseDegradations,
+  readerFacing,
+} from "./state/degradations.js";
+export type {
+  SearchCountKind,
+  SearchDegradationAudience,
 } from "./state/degradations.js";
-export type { SearchCountKind } from "./state/degradations.js";
 
 export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
 export type {
@@ -105,6 +110,7 @@ export type {
 export {
   RANGE_FEATURE_TYPES,
   buildRangeGroups,
+  coreRangeLabelKey,
   isRangeFeature,
   isRangeUsable,
 } from "./state/ranges.js";
@@ -113,6 +119,8 @@ export type { BuildRangeGroupsInput, RangeGroup } from "./state/ranges.js";
 export {
   SEARCH_BOX_DEBOUNCE_MS,
   SEARCH_BOX_SUGGEST_DEBOUNCE_MS,
+  SEARCH_COUNT_DEBOUNCE_MS,
+  SEARCH_COUNT_PAGE_SIZE,
   SEARCH_DEFAULT_PAGE_SIZE,
   SEARCH_MAX_PAGE_SIZE,
   SEARCH_QUERY_MAX_CHARS,
@@ -152,6 +160,12 @@ export type { FacetPanelBag } from "./headless/FacetPanel.js";
 export { useAppliedSort } from "./headless/useAppliedSort.js";
 export { useSearchBox } from "./headless/useSearchBox.js";
 export type { SearchBoxBag, UseSearchBoxOptions } from "./headless/useSearchBox.js";
+export { countQueryState, useSearchCount } from "./headless/useSearchCount.js";
+export type {
+  SearchCount,
+  SearchCountState,
+  UseSearchCountOptions,
+} from "./headless/useSearchCount.js";
 export { RankingDisclosure } from "./headless/RankingDisclosure.js";
 export type { RankingDisclosureBag } from "./headless/RankingDisclosure.js";
 

package/src/state/degradations.ts

@@ -133,3 +133,59 @@ export function isCountNuanceOnly(
     degradations.every((degradation) => degradation.kind === "exact_total")
   );
 }
+
+/**
+ * Who a degradation is addressed to.
+ *
+ * - `"reader"` — it changes what THIS PAGE MEANS. "Counts are approximate",
+ *   "subcategories may be missing", "a ranking parameter is inactive", and
+ *   anything this build has no wording for. A buyer can act on these: read
+ *   the numbers as estimates, widen the category, distrust the order.
+ * - `"operator"` — it describes the ENGINE THIS DEPLOYMENT CHOSE. Nothing a
+ *   buyer does changes it, and it is the same sentence on every query
+ *   forever, which is precisely what makes it invisible by the time it
+ *   matters.
+ */
+export type SearchDegradationAudience = "reader" | "operator";
+
+const OPERATOR_KINDS: ReadonlySet<string> = new Set<SearchDegradationKind>([
+  // Both of these say, in the shipped copy, "the search engine in use
+  // cannot do this" — a sentence about a procurement decision, printed at a
+  // person trying to buy a phone.
+  "typo_tolerance",
+  "phrase_synonyms",
+  // A count nuance the count itself already speaks, as "N+". This is the
+  // rule `isCountNuanceOnly` encoded for one kind, generalized.
+  "exact_total",
+]);
+
+/** {@link SearchDegradationAudience} for one kind. */
+export function degradationAudience(
+  kind: SearchDegradationKind
+): SearchDegradationAudience {
+  return OPERATOR_KINDS.has(kind) ? "operator" : "reader";
+}
+
+/**
+ * The degradations a buyer should be told about.
+ *
+ * The live defect this exists for: a classified board raised a full-screen
+ * yellow "What this search could not do: synonyms were not substituted —
+ * the search engine in use cannot do this" between the sort control and
+ * the first card, on every query, for every buyer. It was not a lie about a
+ * broken thing — stapel-search really did report `phrase_synonyms` on every
+ * query with text — which is exactly why deleting the STRING would have been
+ * the wrong fix: the next engine-capability literal would have grown its own
+ * copy of it. What is wrong is the AUDIENCE, so the audience is the thing
+ * that got a name.
+ *
+ * `variant="debug"` on `<DegradationNotice>` shows the operator's half; a
+ * host that wants it on a status page renders that.
+ */
+export function readerFacing(
+  degradations: readonly SearchDegradation[]
+): readonly SearchDegradation[] {
+  return degradations.filter(
+    (degradation) => degradationAudience(degradation.kind) === "reader"
+  );
+}