@stapel/search-react 0.10.0 → 0.12.0

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -102,13 +102,24 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * Title prefixes from the index
-         * @description ``GET /search/api/v1/suggest`` — title prefixes out of the index.
+         * Type-ahead: category paths with live counts, plus title prefixes
+         * @description ``GET /search/api/v1/suggest`` — what to offer under the search box.
          *
-         *     Not out of a query log: no query log is kept, which is a privacy
+         *     ``categories`` is the primary half: each row is a destination with its
+         *     full ancestor path and the number of listings a buyer would actually
+         *     see there, ranked by that number. ``terms`` is the title-prefix half.
+         *
+         *     Neither comes from a query log: no query log is kept, which is a privacy
          *     decision before it is a product one, and on day one there would be
          *     nothing in it anyway.
          *
+         *     The answer is public, identical for every reader and requested on every
+         *     keystroke, so it carries ``Cache-Control: public`` and an ``ETag``. This
+         *     is the module's first conditional read — ``query`` has none, because a
+         *     SERP answer embeds ``took_ms`` and a cursor and would revalidate to a
+         *     miss every time. Here the payload is deliberately free of anything that
+         *     varies with the clock.
+         *
          *     **Permissions:** `AllowAny`
          */
         get: operations["search_api_v1_suggest_retrieve"];
@@ -124,6 +135,38 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /** @description One destination in the dropdown, ready to render and ready to follow. */
+        CategorySuggestion: {
+            /** @description Category id. */
+            id: number;
+            /** @description Category slug. */
+            slug: string;
+            /** @description The category's own display name. */
+            name: string;
+            /** @description Display names root->leaf, e.g. ['Мужская одежда', 'Шорты']. This is what distinguishes three categories that share a name. */
+            path: string[];
+            /** @description The ancestry as ids joined with '/'. Pass it verbatim as the `category` parameter of /query — do not re-join path segments yourself. */
+            category: string;
+            /** @description Live listings a buyer would see under this category, descendants included — the same number the SERP reports for it. */
+            count: number;
+            /** @description Number of segments in `path`. */
+            depth: number;
+            /**
+             * @description How the name matched. Informational; ranking is by `count`.
+             *
+             *     * `prefix` - prefix
+             *     * `substring` - substring
+             */
+            match: components["schemas"]["MatchEnum"];
+        };
+        /** @description Captions for one slug's option codes. */
+        FacetLabels: {
+            /** @description True when `values` holds translation KEYS to run through the catalogue; false when it holds literal captions. The reader cannot tell by looking — `b.apple` and `Б/у` are both strings. */
+            translatable: boolean;
+            values: {
+                [key: string]: string;
+            };
+        };
         FacetMeta: {
             /** @description True when counts came from a sample because the candidate set exceeded FACET_CANDIDATE_CAP. */
             approximate: boolean;
@@ -132,6 +175,8 @@ export interface components {
             counted: string[];
             /** @description Plan slugs dropped at MAX_FACET_FIELDS — reported, not vanished. */
             skipped: string[];
+            /** @description Range slugs that address a core document column rather than an attribute (`r.price`). Offer them as filters unconditionally: they exist for every document in every category, which is why they are not in the category's own plan. */
+            core_ranges: string[];
         };
         HealthResponse: {
             backend: string;
@@ -145,6 +190,12 @@ export interface components {
             lag_seconds?: number | null;
             stale_reason?: string;
         };
+        /**
+         * @description * `prefix` - prefix
+         *     * `substring` - substring
+         * @enum {string}
+         */
+        MatchEnum: "prefix" | "substring";
         /** @description The P2B Art. 5 disclosure, generated from the scorer registry. */
         RankingResponse: {
             doc_type: string;
@@ -208,6 +259,10 @@ export interface components {
                     [key: string]: number;
                 };
             };
+            /** @description {slug: {translatable, values: {value: caption}}} for slugs whose options are inline in the category schema. Absent for a vocabulary-backed slug: its level lives outside the schema and the plan will not invent a caption it has not read. */
+            facet_labels: {
+                [key: string]: components["schemas"]["FacetLabels"];
+            };
             facet_meta: components["schemas"]["FacetMeta"];
             next_anchor: string | null;
             prev_anchor: string | null;
@@ -222,11 +277,22 @@ export interface components {
             /** @description What the configured engine could not do for this query. */
             degraded: string[];
             backend: string;
+            /** @description The language whose dictionary and analyzer configuration answered — `lang`, else Accept-Language, else DEFAULT_LANGUAGE. When the fallback is wrong the synonym layer silently does not apply, and this field is the only place the answer says so. */
+            language: string;
             sort: string;
             took_ms: number;
         };
         SuggestResponse: {
+            /** @description Destinations, ranked by live listing count desc, then depth, then name. */
+            categories: components["schemas"]["CategorySuggestion"][];
+            /** @description Title prefixes from the index. */
+            terms: string[];
+            /** @description Deprecated alias of `terms`, kept for one minor. */
             items: string[];
+            /** @description Which dictionary answered — the same resolution /query reports. */
+            language: string;
+            /** @description What this answer could not do: `category_suggestions` (no provider for category names), `category_rollup` (no ancestry, so counts would read 0). */
+            degraded: string[];
             backend: string;
         };
     };
@@ -356,11 +422,15 @@ export interface operations {
     };
     search_api_v1_suggest_retrieve: {
         parameters: {
-            query: {
+            query?: {
+                /** @description Language of the query: picks the dictionary, so «shorty» reaches «шорты». Falls back to Accept-Language, then DEFAULT_LANGUAGE. */
+                lang?: string;
+                /** @description Rows per half. Capped by MAX_SUGGEST_LIMIT. */
                 limit?: number;
-                /** @description Title prefix. */
+                /** @description What the buyer has typed so far. */
                 q?: string;
-                type: string;
+                /** @description Registered doc_type. Optional when exactly one type is registered — a type-ahead should not have to name the only corpus there is. */
+                type?: string;
             };
             header?: never;
             path?: never;

package/src/api/searchApi.ts

@@ -3,8 +3,8 @@ import type {
   RankingResponse,
   SearchQueryState,
   SearchResponse,
+  SuggestAnswer,
   SuggestParams,
-  SuggestResponse,
 } from "./types.js";
 
 /**
@@ -53,15 +53,22 @@ export interface SearchApi {
   ): Promise<SearchResponse>;
 
   /**
-   * Title-prefix suggestions. Typed and callable, but this pair ships NO hook
-   * and no autocomplete widget over it (spec §4.2 defers the debounce +
-   * keyboard work). A host that wants one today calls this directly rather
-   * than waiting for a version of the pair that has it.
+   * What to offer under the search box: CATEGORIES first, then title-prefix
+   * terms (stapel-search 0.7.0).
+   *
+   * Neither half comes from a query log — the module keeps none, which is a
+   * privacy decision before it is a product one — so every suggestion is a
+   * destination or a search that has results.
+   *
+   * Typed as {@link SuggestAnswer} rather than as the generated
+   * `SuggestResponse`: a build regenerated against a pre-0.7.0 schema would
+   * otherwise hide the categories half from the compiler. See that type for
+   * why every member but `backend` is optional.
    */
   suggest(
     params: SuggestParams,
     options?: { readonly signal?: AbortSignal }
-  ): Promise<SuggestResponse>;
+  ): Promise<SuggestAnswer>;
 
   /**
    * The P2B Art. 5 ranking disclosure for a doc type: which parameters rank

package/src/api/types.ts

@@ -25,9 +25,123 @@ export type SearchItem = Schemas["SearchItem"];
  * `counted`, `skipped`. Rendered, never swallowed (spec §4.2). */
 export type FacetMeta = Schemas["FacetMeta"];
 
-/** `GET /suggest` 200. */
+/** `GET /suggest` 200, as the CURRENT generated schema describes it. */
 export type SuggestResponse = Schemas["SuggestResponse"];
 
+/**
+ * How a category's name matched the typed prefix. Informational — the server
+ * ranks by `count`, never by this.
+ */
+export type SuggestCategoryMatch = "prefix" | "substring";
+
+/**
+ * One CATEGORY the type-ahead offers: a destination, not a search term.
+ *
+ * A classified's search box is a navigation control before it is a text
+ * filter. "Shorts" is not one destination but three — men's, women's,
+ * children's — and the only things that let a buyer pick between them are the
+ * ancestor path and how many live listings sit behind each. Both are here,
+ * and neither can be computed on the client: the count is one aggregate over
+ * the index, and a client-side matcher over a fetched tree would have the
+ * names and no numbers.
+ */
+export interface SuggestCategory {
+  readonly id: number;
+  readonly slug: string;
+  /** The category's own display name. */
+  readonly name: string;
+  /**
+   * Display names root→leaf, e.g. `["Menswear", "Shorts"]` — this is what
+   * distinguishes three categories sharing a name, and it is what a row has
+   * to print.
+   */
+  readonly path: readonly string[];
+  /**
+   * The ancestry as ids joined with `/`, ready to pass VERBATIM as the
+   * `category` parameter of `/query`.
+   *
+   * The server serves the joined string rather than only the segments
+   * precisely so that a client cannot invent a different join and silently
+   * miss — so nothing in this pair rebuilds it from {@link path} or
+   * {@link slug}.
+   */
+  readonly category: string;
+  /**
+   * Live listings a buyer would see under this category, descendants
+   * included — the same number the SERP reports for it.
+   */
+  readonly count: number;
+  /** Number of segments in {@link path}. */
+  readonly depth: number;
+  readonly match: SuggestCategoryMatch;
+}
+
+/**
+ * The `/suggest` answer this pair actually reads.
+ *
+ * GENERATOR NOTE, and the reason this is not `Schemas["SuggestResponse"]`:
+ * the generated type describes ONE server. stapel-search 0.7.0 made the answer
+ * three-part — `categories`, `terms`, and `items` as a deprecated alias of
+ * `terms` — plus `language` and `degraded`, and declares all five REQUIRED,
+ * which is true of a 0.7.0 answer and false of every answer sent by the
+ * servers a storefront is also deployed against.
+ *
+ * Every member but `backend` is therefore OPTIONAL here, which is not
+ * sloppiness but the deployment story: a storefront ships against whichever
+ * server is actually running, an older one sends no `categories` key at all,
+ * and "the key is absent" has to read as "this server offers no destinations"
+ * rather than as a crash or as an empty group under a heading. A pair typed
+ * against the required-field version would compile while reading `undefined`
+ * from a field the compiler swore was there.
+ */
+export interface SuggestAnswer {
+  readonly backend: string;
+  /** Destinations, ranked by live listing count desc, then depth, then name. */
+  readonly categories?: readonly SuggestCategory[];
+  /** Title prefixes from the index. */
+  readonly terms?: readonly string[];
+  /** Deprecated alias of {@link terms}, and the only half a pre-0.7.0 server
+   * sends. Read through {@link suggestTerms}, never directly. */
+  readonly items?: readonly string[];
+  /** Which dictionary answered — the same resolution `/query` reports. */
+  readonly language?: string;
+  /** What this answer could not do — see {@link SUGGEST_DEGRADED_CATEGORIES}
+   * and {@link SUGGEST_DEGRADED_ROLLUP}. */
+  readonly degraded?: readonly string[];
+}
+
+/**
+ * The suggest answer had NO category provider, so the categories half is
+ * empty for a reason that is not "nothing matched".
+ *
+ * A dropdown has no room for a sentence about a provider being down, and the
+ * person reading it is mid-word. So the group is ABSENT rather than empty —
+ * an empty group under a heading is the box claiming the catalogue has no
+ * section by that name, which is a different and untrue statement.
+ */
+export const SUGGEST_DEGRADED_CATEGORIES = "category_suggestions";
+
+/**
+ * Ancestry never arrived, so every stored path is one segment long and every
+ * count would read `0`.
+ *
+ * The rows are still destinations and still worth offering; their COUNTS are
+ * the part that is not an answer, so a surface drops the number rather than
+ * printing a catalogue of zeros.
+ */
+export const SUGGEST_DEGRADED_ROLLUP = "category_rollup";
+
+/**
+ * The term half of a suggest answer, from whichever key this server sends.
+ *
+ * `terms` is 0.7.0's name and `items` is the deprecated alias kept for one
+ * minor; a client that read only one of them would go blank against half the
+ * servers in the fleet.
+ */
+export function suggestTerms(answer: SuggestAnswer | undefined): readonly string[] {
+  return answer?.terms ?? answer?.items ?? [];
+}
+
 /** `GET /ranking` 200 — the P2B Art. 5 disclosure. */
 export type RankingResponse = Schemas["RankingResponse"];
 

package/src/default/DegradationNotice.tsx

@@ -12,27 +12,34 @@
  *
  * ── Two deliberate ways NOT to shout ───────────────────────────────────────
  *
- * 1. **`exact_total` alone never raises a banner.** It is a count NUANCE, not
- *    a failed search: the rows are right, and the single consequence — that
- *    the total is a floor — is already spoken by the count as "N+". A warning
- *    box over a perfectly good result page teaches the reader that the page
- *    is broken, and a banner that cries wolf on every landing page is a
- *    banner nobody reads on the day `category_rollup` appears in it. Beside
- *    any other degradation it renders normally, because the list is then
- *    describing an answer that really is degraded. See
- *    {@link isCountNuanceOnly}.
+ * 1. **A degradation addressed to the OPERATOR never reaches the reader.**
+ *    `typo_tolerance` and `phrase_synonyms` both say, in the shipped ru copy,
+ *    "the search engine in use cannot do this" — a sentence about which
+ *    engine somebody licensed, printed at a person trying to buy a phone. It
+ *    is the same sentence on every query forever, which is what makes it
+ *    invisible by the day `category_rollup` shows up in the same box.
+ *    `exact_total` joins them: the count already says "N+".
+ *
+ *    Measured live on a classified board: a full-screen yellow "synonyms
+ *    were not substituted" between the sort control and the first card, on every
+ *    query, for every buyer. Note what the fix is NOT — the string was not
+ *    deleted and the kind was not special-cased. `readerFacing` names the
+ *    *audience*, so the next engine-capability literal is filtered by the
+ *    same rule instead of growing its own copy of this comment.
  * 2. **`variant`.** A catalogue page wants the banner; a landing page that
  *    shows six cards under a hero has no room for a warning box and passes
- *    `"inline"` (one quiet line) or `"off"`. `"off"` is a decision the
- *    CONTAINER makes about ITS surface — the notice stays the default, and
- *    nothing here silences a degradation for everyone.
+ *    `"inline"` (one quiet line) or `"off"`. `"debug"` is the operator's
+ *    view: everything, unfiltered, for a status page or a support tool.
+ *    `"off"` is a decision the CONTAINER makes about ITS surface — the
+ *    notice stays the default, and nothing here silences a reader-facing
+ *    degradation for everyone.
  */
 import type { ReactElement } from "react";
 import { Alert, Flex, Typography } from "antd";
 import { fontSize, spacing } from "@stapel/tokens";
 import { useT } from "@stapel/core";
 import type { SearchDegradation } from "../api/types.js";
-import { isCountNuanceOnly } from "../state/degradations.js";
+import { readerFacing } from "../state/degradations.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
 /**
@@ -40,10 +47,12 @@ import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
  *
  * - `"banner"` (default) — an antd warning `Alert` with one line per item.
  * - `"inline"` — the same sentences as quiet secondary text, no box.
+ * - `"debug"` — every degradation including the operator's, for a status page
+ *   or a support tool. The one variant that does not filter by audience.
  * - `"off"` — nothing. For a surface where the notice does not belong at all;
  *   the container that turns it off owns saying so somewhere else.
  */
-export type DegradationNoticeVariant = "banner" | "inline" | "off";
+export type DegradationNoticeVariant = "banner" | "inline" | "debug" | "off";
 
 export interface DegradationNoticeProps {
   readonly degradations: readonly SearchDegradation[];
@@ -63,9 +72,10 @@ export function DegradationNotice(
   const t = useT();
   const variant: DegradationNoticeVariant = props.variant ?? "banner";
   if (variant === "off") return null;
-  if (props.degradations.length === 0) return null;
-  // A count nuance is not a degraded search — the count already says "N+".
-  if (isCountNuanceOnly(props.degradations)) return null;
+  // Everything, or only what this page's reader can act on.
+  const degradations =
+    variant === "debug" ? props.degradations : readerFacing(props.degradations);
+  if (degradations.length === 0) return null;
 
   const say = (degradation: SearchDegradation): string => {
     const slug = degradation.scorer;
@@ -82,7 +92,7 @@ export function DegradationNotice(
   // theme's warning tint, and grey body text on it measured under 3:1 in the
   // visual pass. Inside a coloured box the readable colour is the box's own
   // text colour, which is what a plain `<Typography.Text>` inherits.
-  const lines = props.degradations.map((degradation) => (
+  const lines = degradations.map((degradation) => (
     <li key={degradation.raw} data-degradation={degradation.raw}>
       <Typography.Text>{say(degradation)}</Typography.Text>
     </li>
@@ -95,7 +105,7 @@ export function DegradationNotice(
           {t(SEARCH_I18N_KEYS.degradedTitle)}
         </Typography.Text>
         <ul style={{ margin: 0, paddingInlineStart: spacing[5], fontSize: fontSize.xs.fontSize }}>
-          {props.degradations.map((degradation) => (
+          {degradations.map((degradation) => (
             <li key={degradation.raw} data-degradation={degradation.raw}>
               <Typography.Text type="secondary">{say(degradation)}</Typography.Text>
             </li>
@@ -110,7 +120,7 @@ export function DegradationNotice(
       type="warning"
       showIcon
       data-testid="search-degraded"
-      data-variant="banner"
+      data-variant={variant === "debug" ? "debug" : "banner"}
       title={t(SEARCH_I18N_KEYS.degradedTitle)}
       description={
         <ul style={{ margin: 0, paddingInlineStart: spacing[5] }}>{lines}</ul>

package/src/default/FacetPanelPane.tsx

@@ -54,6 +54,7 @@ import { featureName } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
 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 { FacetGroupControl } from "./FacetGroupControl.js";
 import { buildRangeGroups } from "../state/ranges.js";
@@ -78,11 +79,21 @@ export interface GeoFilterSlotProps {
 }
 
 export interface FacetPanelPaneProps extends ThemeModeProp {
-  /** The category's feature schema — the source of option LABELS and of which
-   * slugs get a numeric range row. */
+  /** The category's feature schema — the source of option LABELS, of which
+   * slugs get a numeric range row, and of which slugs are a filter at all
+   * (`isFacetableFeature`: an `imei` is counted and is not one). */
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
   readonly enabled?: boolean;
+  /**
+   * Name the values neither the answer nor the schema names — see
+   * {@link FacetLabelResolver}. A `ref_select` facet carries only a pointer to
+   * a vocabulary in its config, and the vocabulary is the host's to read.
+   *
+   * The same prop reaches `<FilterChips>` from `<SearchPage>`, so the panel
+   * and the chip row cannot print two different words for one value.
+   */
+  readonly resolveFacetLabels?: FacetLabelResolver;
   /** The catalogue picker (`categories-react`'s `CategoryPickerField`, bound
    * to a path). Unfilled, an active category still gets a "clear" control. */
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
@@ -306,13 +317,6 @@ function skippedNames(
 export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
   const t = useT();
   const { state } = useSearchState();
-  const ranges = buildRangeGroups({
-    state,
-    ...(props.categoryFeatures !== undefined
-      ? { categoryFeatures: props.categoryFeatures }
-      : {}),
-    t,
-  });
 
   return (
     <SkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
@@ -322,8 +326,28 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
           : {})}
         {...(props.locale !== undefined ? { locale: props.locale } : {})}
         {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}
+        {...(props.resolveFacetLabels !== undefined
+          ? { resolveFacetLabels: props.resolveFacetLabels }
+          : {})}
       >
-        {(bag) => (
+        {(bag) => {
+          // Built INSIDE the bag, because which axes exist is a property of
+          // the ANSWER now: `facet_meta.core_ranges` names the core columns
+          // this server can actually filter on (`r.price`), and the corpus
+          // currency is read off the cards it just returned. Computed
+          // outside, the panel would have had to keep its own list of core
+          // slugs — which is how a board ends up offering a price filter
+          // against a server that answers zero for one.
+          const ranges = buildRangeGroups({
+            state,
+            ...(props.categoryFeatures !== undefined
+              ? { categoryFeatures: props.categoryFeatures }
+              : {}),
+            coreRanges: bag.coreRanges,
+            ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
+            t,
+          });
+          return (
           <Flex vertical gap={spacing[3]} data-testid="search-facets">
             <Flex justify="space-between" align="center" gap={spacing[2]}>
               {props.heading === null ? (
@@ -360,6 +384,25 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               {...(props.geoLabel !== undefined ? { label: props.geoLabel } : {})}
             />
 
+            {/* Price first. Every numeric row below it is an ATTRIBUTE the
+                category happens to declare — on the phone board this was
+                measured against, all seven of them were parcel dimensions
+                and wholesale packing. The one number a buyer narrows by is
+                the price, and `buildRangeGroups` puts the core axes first. */}
+            {ranges.length > 0 && (
+              <Flex vertical gap={spacing[3]} data-testid="search-ranges">
+                {ranges.map((group) => (
+                  <RangeFilterRow
+                    key={group.slug}
+                    group={group}
+                    onApply={bag.setRange}
+                  />
+                ))}
+              </Flex>
+            )}
+
+            {ranges.length > 0 && <Divider style={{ margin: 0 }} />}
+
             {/* Honesty flags, not failures: the counts ARE approximate and
                 those slugs WERE skipped, and a red box would teach a person
                 the page is broken. `ErrorAlert` is for a read that did not
@@ -383,20 +426,6 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               />
             )}
 
-            {ranges.length > 0 && (
-              <Flex vertical gap={spacing[3]} data-testid="search-ranges">
-                {ranges.map((group) => (
-                  <RangeFilterRow
-                    key={group.slug}
-                    group={group}
-                    onApply={bag.setRange}
-                  />
-                ))}
-              </Flex>
-            )}
-
-            {ranges.length > 0 && <Divider style={{ margin: 0 }} />}
-
             <LoadList
               state={bag.state}
               testId="facets"
@@ -440,7 +469,8 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               )}
             </LoadList>
           </Flex>
-        )}
+          );
+        }}
       </FacetPanel>
     </SkinTheme>
   );