@stapel/search-react 0.11.0 → 0.12.0

package/dist/state/facets.js

@@ -8,27 +8,86 @@
  *    they would have if you swapped to them. A panel that greys the siblings
  *    out has silently converted a drill-down facet into a naive one, and the
  *    e2e leg in the spec (§7.2) exists to catch exactly that.
- * 2. **Option LABELS come from two places, in that order.** The category's
- *    feature schema — `categoryFeatures`, the second slot-seam of the pair,
- *    filled by the container from `categories-react` (spec §6.2 item 2) —
- *    and, under it, the answer's own `facet_labels` (stapel-search 0.4.0+).
- *
- *    Until 0.4.0 the server sent `{value: count}` and nothing else, on the
- *    reasoning that the container has the schema anyway. That reasoning had
- *    a hole the size of a marketplace: the slot is OPTIONAL, a live
- *    classified board never filled it, and its buyers read "Condition:
- *    **b-u**", "Listing kind: **prodayu-svoe**", "Screen condition:
- *    **bez-defektov**" on the SERP and in the filter chips. The schema still
- *    wins where it resolves — the client fetched it with its own
- *    `Accept-Language` — and the answer's captions are the floor beneath it.
- *    Neither invents a label: a value nobody names renders as itself.
+ * 2. **Option LABELS have one stated order: ANSWER, then schema, then the
+ *    raw value** — with a host resolver between the last two, applied by
+ *    `useHostFacetLabels` on what this module could not name.
+ *
+ *    The answer leads because it is the only source that always exists and
+ *    the only one that has RESOLVED anything: `categoryFeatures` is an
+ *    optional slot a live classified board never filled, and even where it is
+ *    filled a `ref_select` config carries a pointer to a vocabulary and no
+ *    option table at all — so the schema cannot name `apple` or `chernyy` no
+ *    matter who threads it through. `facet_labels` (stapel-search 0.4.0+,
+ *    vocabulary-backed from 0.6.0) is the server reading that vocabulary
+ *    against the snapshot the documents were written with, and answering in
+ *    the request's own language. The schema is the floor under it, for a
+ *    server too old to send captions and for a slug the answer omits.
+ *
+ *    Neither invents a label: a value nobody names renders as itself. A page
+ *    against a pre-0.4.0 server therefore behaves exactly as it did — the key
+ *    is absent, every option falls through to the schema, and nothing
+ *    crashes on the missing key.
  *
  * 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.
+ *
+ * 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
+ *    live classified deployment answers with `imei: {"355971829187494": 1}`
+ *    and `video_file_url: {}` beside its brand and its condition. Neither is
+ *    something a person narrows by — one is unique per document, the other is
+ *    a URL — and on a 390px chip row a chip offering one IMEI with a count of
+ *    one pushes the chips that DO narrow off the screen. Which slugs can be
+ *    chipped is therefore decided from the category's own feature defs, by
+ *    value TYPE (see {@link FACETABLE_FEATURE_TYPES}), not by what came back.
+ */
+import { VOCABULARY_BACKED_TYPES, featureConfig, featureName, featureType, formatFeatureValue, } from "@stapel/attributes-react";
+/**
+ * Value types whose values are a BOUNDED OPTION SET — the only kind of
+ * feature a person can be offered as a filter.
+ *
+ * The list is not invented here: the ref/vocabulary-backed half is
+ * `@stapel/attributes-react`'s own `VOCABULARY_BACKED_TYPES` (the one place
+ * that knows which types are drawn from a vocabulary), and the rest are the
+ * select family plus `bool`. Everything else a category can declare — a
+ * `string`, an `int`, a `date`, a `hex_color`, a `group` — enumerates as many
+ * terms as there are documents, which is a list, not a choice.
+ *
+ * `int`/`float`/`convertible_unit` are absent here and present in
+ * `RANGE_FEATURE_TYPES` (`state/ranges.ts`): a number is narrowed with two
+ * bounds, not with a checkbox per value. They are not dropped from the panel,
+ * they are drawn by the other half of the model.
  */
-import { featureConfig, featureName, featureType, formatFeatureValue } from "@stapel/attributes-react";
+export const FACETABLE_FEATURE_TYPES = [
+    "bool",
+    "hierarchical_select",
+    ...VOCABULARY_BACKED_TYPES,
+    "select",
+];
+/**
+ * Can a person filter by the slug this feature def describes?
+ *
+ * **A missing feature def is not a "no".** `categoryFeatures` is an OPTIONAL
+ * slot and a whole deployment can run without it; a feature can also be
+ * retired between the write that indexed a value and the read that counts it.
+ * Answering "not facetable" for an absent def would blank the entire chip row
+ * for every host that never threaded the schema through — the same empty row
+ * this rule exists to fix, arrived at from the other side. So the schema can
+ * only ever REMOVE a chip it names and disowns; silence removes nothing.
+ *
+ * The same reasoning covers a def with no `config.type` at all: an untyped
+ * feature is a def that says nothing, and nothing is not a verdict.
+ */
+export function isFacetableFeature(feature) {
+    if (feature === undefined)
+        return true;
+    const type = featureType(feature);
+    if (type === undefined)
+        return true;
+    return FACETABLE_FEATURE_TYPES.includes(type);
+}
 function translate(t, key) {
     if (t === undefined)
         return key;
@@ -78,20 +137,23 @@ function declaredOptionValues(feature) {
     return out;
 }
 /**
- * One option's caption: schema, then answer, then the raw value.
- *
- * Order matters and is deliberate. Both sources are the same category
- * config, but the client fetched its copy with its own `Accept-Language`, so
- * where the host threaded a schema through and it names the value, that is
- * the better-localized answer. Where it does not — no schema, a slug the
- * schema omits, a value added since — the server's caption is what stops
- * `b-u` reaching a buyer.
+ * One option's caption: the ANSWER, then the schema, then the raw value.
+ *
+ * The answer leads because it is the source that always exists and the only
+ * one that can name a vocabulary-backed value at all: a `ref_select`'s config
+ * is a POINTER (`optionsRef`), so a host who threaded the whole schema through
+ * still has nothing to print for `apple`. The server read that vocabulary
+ * against the snapshot the documents carry and answered in the request's own
+ * language, which is a strictly better-informed caption than the option table
+ * the schema may or may not hold.
+ *
+ * The schema is the floor: a server too old to send `facet_labels`, a slug the
+ * answer omits, a value the vocabulary has since dropped. Below both, the raw
+ * value — never a blank, and never a guess.
  */
 function resolveLabel(input, feature, slug, value, labelOptions) {
-    const viaSchema = facetOptionLabel(feature, value, labelOptions);
-    if (feature !== undefined && viaSchema !== value)
-        return viaSchema;
-    return serverLabel(input.facetLabels, slug, value, input.t) ?? viaSchema;
+    return (serverLabel(input.facetLabels, slug, value, input.t) ??
+        facetOptionLabel(feature, value, labelOptions));
 }
 /**
  * A facet value as a person reads it, through
@@ -145,6 +207,13 @@ export function facetOptionLabel(feature, value, options) {
  * person has filtered on — the last one matters: a filter whose slug fell out
  * of the plan must stay visible, or it becomes a constraint with no control to
  * remove it.
+ *
+ * A slug the category schema names and types as something no one can choose
+ * from (see {@link isFacetableFeature}) produces no group at all — not an
+ * empty one, because an empty group is still a heading in the panel and still
+ * a chip in the row. The APPLIED-filter clause outranks the type rule: a
+ * constraint the URL carries always gets its control back, whatever the schema
+ * now says about it, or a person is left holding a filter they cannot clear.
  */
 export function buildFacetGroups(input) {
     const bySlug = new Map();
@@ -161,6 +230,11 @@ export function buildFacetGroups(input) {
         if (seen.has(slug))
             continue;
         seen.add(slug);
+        // Applied first, type second — in that order, so an `imei` somebody
+        // somehow got into a link keeps the control that removes it.
+        const applied = (input.state.filters[slug] ?? []).length > 0;
+        if (!applied && !isFacetableFeature(bySlug.get(slug)))
+            continue;
         slugs.push(slug);
     }
     return slugs.map((slug) => {

package/dist/state/facets.js.map

@@ -1 +1 @@
-{"version":3,"file":"facets.js","sourceRoot":"","sources":["../../src/state/facets.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"facets.js","sourceRoot":"","sources":["../../src/state/facets.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/search-react 0.11.0
+# @stapel/search-react 0.12.0
 
-Headless React flow pair for stapel-search (contract >=0.4 <0.5) — business + state, zero visual opinion.
+Headless React flow pair for stapel-search (contract >=0.7 <0.8) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "backend": {
     "module": "stapel-search",
-    "contract": ">=0.4 <0.5"
+    "contract": ">=0.7 <0.8"
   },
   "layers": [
     "api",
@@ -703,6 +703,10 @@
     "error.500.internal",
     "error.503.mandate_unavailable",
     "error.503.search_backend_unavailable",
+    "search.box.categories",
+    "search.box.category_count",
+    "search.box.category_count.one",
+    "search.box.category_count.other",
     "search.box.clear",
     "search.box.label",
     "search.box.placeholder",
@@ -745,6 +749,7 @@
     "search.filters.chips_label",
     "search.filters.dismiss",
     "search.filters.open",
+    "search.filters.short",
     "search.filters.show_count",
     "search.filters.show_count.one",
     "search.filters.show_count.other",
@@ -763,6 +768,9 @@
     "search.limit.from_link",
     "search.limit.label",
     "search.limit.option",
+    "search.nav.ranking",
+    "search.nav.ranking.short",
+    "search.nav.results",
     "search.range.price",
     "search.ranking.applies_to",
     "search.ranking.empty",
@@ -819,6 +827,7 @@
   ],
   "exports": {
     "runtime": [
+      "FACETABLE_FEATURE_TYPES",
       "FILTER_PREFIX",
       "FacetPanel",
       "RANGE_FEATURE_TYPES",
@@ -839,6 +848,8 @@
       "SEARCH_QUERY_MAX_CHARS",
       "SEARCH_SORTS",
       "SEARCH_WINDOW_EXCEEDED",
+      "SUGGEST_DEGRADED_CATEGORIES",
+      "SUGGEST_DEGRADED_ROLLUP",
       "SUGGEST_MAX_LIMIT",
       "SUGGEST_MIN_CHARS",
       "SearchProvider",
@@ -860,9 +871,11 @@
       "explainSearchError",
       "facetOptionLabel",
       "isCountNuanceOnly",
+      "isFacetableFeature",
       "isRangeFeature",
       "isRangeUsable",
       "navEntries",
+      "offerableCategories",
       "ownsParam",
       "parseDegradations",
       "parseSearchState",
@@ -875,9 +888,11 @@
       "searchQueryParams",
       "setFilterValues",
       "setRangeValue",
+      "suggestTerms",
       "toggleFilterValue",
       "useAppliedSort",
       "useFacetPanel",
+      "useHostFacetLabels",
       "useRankingDisclosure",
       "useSearchAnalytics",
       "useSearchApi",
@@ -894,6 +909,8 @@
       "BuildRangeGroupsInput",
       "CreateSearchRuntimeOptions",
       "FacetGroup",
+      "FacetLabelRequest",
+      "FacetLabelResolver",
       "FacetMeta",
       "FacetOption",
       "FacetPanelBag",
@@ -934,6 +951,9 @@
       "SearchStateIssueCode",
       "SearchStatePatch",
       "SearchStateProviderProps",
+      "SuggestAnswer",
+      "SuggestCategory",
+      "SuggestCategoryMatch",
       "SuggestParams",
       "SuggestResponse",
       "UseSearchBoxOptions",

package/nav-manifest.json

@@ -1,10 +1,10 @@
 {
   "package": "@stapel/search-react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "entries": [
     {
       "id": "search.results",
-      "labelKey": "search.results.title",
+      "labelKey": "search.nav.results",
       "icon": "SearchOutlined",
       "route": {
         "path": "/s"
@@ -23,7 +23,8 @@
     },
     {
       "id": "search.ranking",
-      "labelKey": "search.ranking.title",
+      "labelKey": "search.nav.ranking",
+      "shortLabelKey": "search.nav.ranking.short",
       "icon": "OrderedListOutlined",
       "route": {
         "path": "/ranking-disclosure"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -52,14 +52,14 @@
   ],
   "size-limit": [
     {
-      "name": "index — the headless pair (client + hooks + URL codec + facet model): no antd, no react-router",
+      "name": "index — the headless pair (client + hooks + URL codec + facet model incl. the facetability rule and the host label seam): no antd, no react-router",
       "path": "dist/index.js",
-      "limit": "10 KB"
+      "limit": "10.5 KB"
     },
     {
-      "name": "default — the antd skin (query box + typeahead, filters incl. ranges/geo/category slots + the phone chip row and the location summary row, results incl. the view switch, ranking) must stay out of the main bundle",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row, results incl. the view switch, ranking) must stay out of the main bundle",
       "path": "dist/default/index.js",
-      "limit": "18 KB"
+      "limit": "19.5 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -78,10 +78,10 @@
     }
   ],
   "peerDependencies": {
-    "@stapel/attributes-react": ">=0.1.0",
+    "@stapel/attributes-react": ">=0.4.0",
     "@stapel/core": ">=0.18.1 <1.0.0",
     "@stapel/image": ">=0.3.0",
-    "@stapel/tokens-antd": ">=0.7.0",
+    "@stapel/tokens-antd": ">=0.11.0",
     "@tanstack/react-query": "^5.0.0",
     "antd": ">=5.20.0 <7",
     "react": ">=19",
@@ -115,12 +115,12 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.5.0",
-    "@stapel/core": "^0.21.0",
+    "@stapel/attributes-react": "^0.6.0",
+    "@stapel/core": "^0.22.0",
     "@stapel/image": "^0.4.2",
+    "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.6.0",
-    "@stapel/tokens-antd": "^0.10.0",
-    "@stapel/showcase": "^0.3.0"
+    "@stapel/tokens-antd": "^0.11.0"
   },
   "engines": {
     "node": ">=22"

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.11.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,30 @@ 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. */
@@ -155,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;
@@ -242,7 +283,16 @@ export interface components {
             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;
         };
     };
@@ -372,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