@stapel/search-react 0.1.0

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@stapel/search-react",
+  "version": "0.1.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": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/search-react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./default": {
+      "types": "./dist/default/index.d.ts",
+      "default": "./dist/default/index.js"
+    },
+    "./router": {
+      "types": "./dist/router/index.d.ts",
+      "default": "./dist/router/index.js"
+    },
+    "./i18n/ru": {
+      "types": "./dist/i18n/ru.d.ts",
+      "default": "./dist/i18n/ru.js"
+    },
+    "./i18n/es": {
+      "types": "./dist/i18n/es.d.ts",
+      "default": "./dist/i18n/es.js"
+    },
+    "./manifest": "./manifest.json",
+    "./manifest.json": "./manifest.json",
+    "./nav-manifest.json": "./nav-manifest.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "MODULE.md",
+    "CHANGELOG.md",
+    "manifest.json",
+    "nav-manifest.json",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && vitest run --exclude test/prodBundlePurity.test.ts",
+    "lint": "eslint .",
+    "size": "size-limit",
+    "test:pack": "vitest run test/prodBundlePurity.test.ts"
+  },
+  "size-limit": [
+    {
+      "name": "index — the headless pair (client + hooks + URL codec + facet model): no antd, no react-router",
+      "path": "dist/index.js",
+      "limit": "10 KB"
+    },
+    {
+      "name": "default — the antd skin (results, facet panel, degradation notice, ranking disclosure) must stay out of the main bundle",
+      "path": "dist/default/index.js",
+      "limit": "13 KB"
+    },
+    {
+      "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
+      "path": "dist/router/index.js",
+      "limit": "1 KB"
+    },
+    {
+      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/ru.js",
+      "limit": "4.5 KB"
+    },
+    {
+      "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry",
+      "path": "dist/i18n/es.js",
+      "limit": "3.5 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@stapel/attributes-react": ">=0.1.0",
+    "@stapel/core": ">=0.15.0 <1.0.0",
+    "@stapel/tokens-antd": ">=0.5.0",
+    "@tanstack/react-query": "^5.0.0",
+    "antd": ">=5.20.0 <7",
+    "react": ">=19",
+    "react-router": ">=7.0.0 <8"
+  },
+  "peerDependenciesMeta": {
+    "@stapel/tokens-antd": {
+      "optional": true
+    },
+    "antd": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@stapel/attributes-react": "workspace:^",
+    "@stapel/core": "workspace:^",
+    "@stapel/showcase": "workspace:^",
+    "@stapel/tokens": "workspace:^",
+    "@stapel/tokens-antd": "workspace:^",
+    "@tanstack/react-query": "^5.81.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "antd": "^6.5.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router": "^7.18.1",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analytics/generated/events.json

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

package/src/api/generated/schema.ts

@@ -0,0 +1,377 @@
+// AUTO-GENERATED by scripts/gen-api.mjs — do not edit by hand.
+// Source: the backend module's own docs/schema.json (§17-native per-module contract).
+// Regenerate: pnpm gen:api   ·   Drift gate: pnpm gen:api:check
+export interface paths {
+    "/search/api/v1/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Engine reachability, capabilities and index lag
+         * @description ``GET /search/api/v1/health`` — backend, capabilities, index lag.
+         *
+         *     **Permissions:** `IsNotAnonymousUser`
+         */
+        get: operations["search_api_v1_health_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/api/v1/query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search one registered document type
+         * @description ``GET /search/api/v1/query`` — the whole read contract.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["search_api_v1_query_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/api/v1/ranking": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Ranking disclosure (P2B Art. 5), generated from the scorer registry
+         * @description ``GET /search/api/v1/ranking`` — the P2B Art. 5 disclosure.
+         *
+         *     Generated from the scorer registry and annotated with what the
+         *     configured engine can actually evaluate, so it cannot claim a parameter
+         *     is in effect when the backend cannot compute it.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["search_api_v1_ranking_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/api/v1/reindex": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Re-pull specific keys, or rebuild a whole document type
+         * @description ``POST /search/api/v1/reindex`` — targeted re-pull or a full rebuild.
+         *
+         *     **Permissions:** `IsNotAnonymousUser`
+         */
+        post: operations["search_api_v1_reindex_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/api/v1/suggest": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Title prefixes from the index
+         * @description ``GET /search/api/v1/suggest`` — title prefixes out of the index.
+         *
+         *     Not out of 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.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["search_api_v1_suggest_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        FacetMeta: {
+            /** @description True when counts came from a sample because the candidate set exceeded FACET_CANDIDATE_CAP. */
+            approximate: boolean;
+            /** @description Size of the largest counted set. */
+            candidates: number;
+            counted: string[];
+            /** @description Plan slugs dropped at MAX_FACET_FIELDS — reported, not vanished. */
+            skipped: string[];
+        };
+        HealthResponse: {
+            backend: string;
+            reachable: boolean;
+            detail: string;
+            documents?: number | null;
+            capabilities?: {
+                [key: string]: unknown;
+            };
+            types: string[];
+            lag_seconds?: number | null;
+            stale_reason?: string;
+        };
+        /** @description The P2B Art. 5 disclosure, generated from the scorer registry. */
+        RankingResponse: {
+            doc_type: string;
+            backend: string;
+            scorers: components["schemas"]["Scorer"][];
+            notes: string[];
+        };
+        ReindexRequest: {
+            doc_type: string;
+            /** @description Re-pull exactly these keys; omit to rebuild the whole type. */
+            keys?: string[];
+        };
+        ReindexResponse: {
+            doc_type: string;
+            indexed: number;
+            removed: number;
+            skipped_stale: number;
+            skipped_duplicate: number;
+        };
+        Scorer: {
+            slug: string;
+            /** Format: double */
+            weight: number;
+            description_key: string;
+            description: string;
+            params: {
+                [key: string]: unknown;
+            };
+            applies_to_sorts: string[];
+            /** @description False when the configured engine cannot evaluate this parameter. */
+            active: boolean;
+            inactive_reason: string;
+        };
+        /** @description One result row. */
+        SearchItem: {
+            /** @description The source's own document key. */
+            key: string;
+            /**
+             * Format: double
+             * @description Ranking score; 0 under an explicit sort.
+             */
+            score: number;
+            /** @description Whether this result is promoted. Present on EVERY item under EVERY sort, including when false — a mandatory marking (DSA Art. 26), not an optional field. */
+            promoted: boolean;
+            /**
+             * Format: double
+             * @description Great-circle distance from the searched centre.
+             */
+            distance_km: number | null;
+            /** @description Stored row fields, so a result page costs one query. */
+            card: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description The query envelope: AnchorPagination's keys, plus what search owes. */
+        SearchResponse: {
+            items: components["schemas"]["SearchItem"][];
+            /** @description {slug: {value: count}}, counted with the slug's own filter removed. */
+            facets: {
+                [key: string]: {
+                    [key: string]: number;
+                };
+            };
+            facet_meta: components["schemas"]["FacetMeta"];
+            next_anchor: string | null;
+            prev_anchor: string | null;
+            has_next: boolean;
+            has_prev: boolean;
+            count: number;
+            exact_total: boolean;
+            /** @description What the configured engine could not do for this query. */
+            degraded: string[];
+            backend: string;
+            sort: string;
+            took_ms: number;
+        };
+        SuggestResponse: {
+            items: string[];
+            backend: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    search_api_v1_health_retrieve: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthResponse"];
+                };
+            };
+        };
+    };
+    search_api_v1_query_retrieve: {
+        parameters: {
+            query: {
+                /** @description Opaque keyset cursor from a previous answer. */
+                anchor?: string;
+                /** @description minLat,minLon,maxLat,maxLon. minLon > maxLon means the box crosses +/-180. */
+                bbox?: string;
+                /** @description root/leaf path; a prefix filter, so a parent finds its descendants. */
+                category?: string;
+                /** @description next | prev. */
+                direction?: string;
+                /** @description Facet filter. Repeat for OR within a slug; different slugs AND together. */
+                "f.<slug>"?: string;
+                /** @description on | off | comma-separated slugs. Default is the category's plan. */
+                facets?: string;
+                /** @description Language of the query: selects the analyzer AND narrows the corpus. Omit it and only the analyzer is chosen (from Accept-Language) — a header must not hide a catalogue. */
+                lang?: string;
+                /** @description Centre latitude (with lon). */
+                lat?: number;
+                limit?: number;
+                /** @description Centre longitude (with lat). */
+                lon?: number;
+                /** @description Opaque owner key — the seller's own listings. */
+                owner?: string;
+                /** @description Free text. Dictionary-normalized here; morphology belongs to the engine. */
+                q?: string;
+                /** @description Range filter, `from..to`; either end may be omitted. */
+                "r.<slug>"?: string;
+                /** @description Radius around the centre. */
+                radius_km?: number;
+                /** @description relevance | newest | price_asc | price_desc | distance. An explicit sort never receives a promotional boost. */
+                sort?: string;
+                /** @description Registered doc_type. One type per query — federated search across types is not in v1. */
+                type: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchResponse"];
+                };
+            };
+        };
+    };
+    search_api_v1_ranking_retrieve: {
+        parameters: {
+            query?: {
+                type?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RankingResponse"];
+                };
+            };
+        };
+    };
+    search_api_v1_reindex_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ReindexRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ReindexRequest"];
+                "multipart/form-data": components["schemas"]["ReindexRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReindexResponse"];
+                };
+            };
+        };
+    };
+    search_api_v1_suggest_retrieve: {
+        parameters: {
+            query: {
+                limit?: number;
+                /** @description Title prefix. */
+                q?: string;
+                type: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestResponse"];
+                };
+            };
+        };
+    };
+}

package/src/api/searchApi.ts

@@ -0,0 +1,169 @@
+import type { StapelClient } from "@stapel/core";
+import type {
+  RankingResponse,
+  SearchQueryState,
+  SearchResponse,
+  SuggestParams,
+  SuggestResponse,
+} from "./types.js";
+
+/**
+ * The pair's typed operation surface — one method per stapel-search endpoint a
+ * storefront may call, bound to the injected {@link StapelClient} (the
+ * per-module override seam of frontend-standard §7.2). Paths are relative to
+ * the runtime's `baseUrl` (`/search/api/v1/`).
+ *
+ * ── The three PUBLIC reads, and the two that are not here ─────────────────
+ *
+ * `query`, `suggest` and `ranking` are `AllowAny` (`stapel_anonymous_access =
+ * ANONYMOUS_ALLOWED`): a storefront calls them with no session at all, which
+ * is what lets a catalogue render for a visitor who will never sign in.
+ *
+ * `GET /health` and `POST /reindex` are NOT on this interface. Both are
+ * `IsNotAnonymousUser` + an in-view `can_manage` check that answers
+ * `error.403.search_forbidden` — they are index-operator endpoints, not
+ * storefront ones, and a pair that exposed them would invite a public screen
+ * to call something only an operator may. They stay in the generated schema
+ * (and therefore in `manifest.json`, which lists the whole contract), so
+ * nothing is hidden; they are simply not this pair's surface.
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2 (task `core-typed-ops`); until then they are hand-authored here (the ONE
+ * legal home of path strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface SearchApi {
+  readonly client: StapelClient;
+
+  /**
+   * One keyset page of results, with the facet counts for the current
+   * candidate set.
+   *
+   * Refusals a skin must tell apart, all 400 with the offending value in
+   * `params`: `error.400.search_unknown_doc_type`, `…_unknown_sort`,
+   * `…_sort_needs_center`, `…_bad_geo`, `…_bad_range`, `…_bad_cursor`,
+   * `…_query_too_long`, `…_too_many_facets`, `…_too_many_ranges`, and
+   * `…_window_exceeded` — which is "narrow the search", NOT "nothing found".
+   * A dead engine answers 503 `error.503.search_backend_unavailable`; the
+   * views turn EVERY backend exception into that, so a 500 never reaches a
+   * client and "we could not ask" is always distinguishable from "no hits".
+   */
+  query(
+    state: SearchQueryState,
+    options?: { readonly signal?: AbortSignal }
+  ): 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.
+   */
+  suggest(
+    params: SuggestParams,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<SuggestResponse>;
+
+  /**
+   * The P2B Art. 5 ranking disclosure for a doc type: which parameters rank
+   * results, their weights, and — per parameter — whether the configured
+   * engine can actually evaluate it (`active` / `inactive_reason`). A
+   * disclosure that listed a parameter the engine ignores would be a
+   * disclosure of the wrong ranking.
+   */
+  ranking(
+    type?: string,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<RankingResponse>;
+}
+
+/**
+ * The wire query object for one search state.
+ *
+ * Exported because it is also what the query KEY is built from: the key and
+ * the request are then the same value by construction, and a filter that
+ * changes the URL but not the key (the classic stale-page bug) cannot happen.
+ *
+ * `f.<slug>` is an ARRAY — repeated keys are the OR, and `@stapel/core`'s
+ * client repeats an array-valued key rather than collapsing it (core 0.15.0).
+ */
+export function searchQueryParams(
+  state: SearchQueryState
+): Record<
+  string,
+  string | number | boolean | undefined | readonly (string | number | boolean)[]
+> {
+  const query: Record<
+    string,
+    | string
+    | number
+    | boolean
+    | undefined
+    | readonly (string | number | boolean)[]
+  > = { type: state.type };
+
+  if (state.q.length > 0) query["q"] = state.q;
+  if (state.lang !== undefined) query["lang"] = state.lang;
+  if (state.category !== undefined) query["category"] = state.category;
+  if (state.owner !== undefined) query["owner"] = state.owner;
+
+  for (const [slug, values] of Object.entries(state.filters)) {
+    if (values.length > 0) query[`f.${slug}`] = values;
+  }
+  for (const [slug, range] of Object.entries(state.ranges)) {
+    if (range.from === undefined && range.to === undefined) continue;
+    query[`r.${slug}`] = `${range.from ?? ""}..${range.to ?? ""}`;
+  }
+
+  if (state.geo !== undefined) {
+    if (state.geo.kind === "bbox") {
+      const { minLat, minLon, maxLat, maxLon } = state.geo;
+      query["bbox"] = `${minLat},${minLon},${maxLat},${maxLon}`;
+    } else {
+      query["lat"] = state.geo.lat;
+      query["lon"] = state.geo.lon;
+      if (state.geo.radiusKm !== undefined) {
+        query["radius_km"] = state.geo.radiusKm;
+      }
+    }
+  }
+
+  if (state.sort !== undefined) query["sort"] = state.sort;
+  if (state.facets !== undefined) {
+    query["facets"] = Array.isArray(state.facets)
+      ? state.facets.join(",")
+      : (state.facets as string);
+  }
+  if (state.anchor !== undefined) query["anchor"] = state.anchor;
+  if (state.direction !== undefined) query["direction"] = state.direction;
+  if (state.limit !== undefined) query["limit"] = state.limit;
+
+  return query;
+}
+
+export function createSearchApi(client: StapelClient): SearchApi {
+  return {
+    client,
+
+    query: (state, options) =>
+      client.get("/query", {
+        query: searchQueryParams(state),
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    suggest: (params, options) =>
+      client.get("/suggest", {
+        query: {
+          type: params.type,
+          ...(params.q !== undefined ? { q: params.q } : {}),
+          ...(params.limit !== undefined ? { limit: params.limit } : {}),
+        },
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+
+    ranking: (type, options) =>
+      client.get("/ranking", {
+        query: type !== undefined ? { type } : {},
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+      }),
+  };
+}