@stapel/search-react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1 +1,55 @@
 # @stapel/search-react
+
+## 0.2.0
+
+### Minor Changes
+
+- 6356af8: New package: `@stapel/search-react` — the frontend pair for stapel-search, and
+  the one surface a storefront's catalogue, category and search pages all come
+  from.
+
+  ```tsx
+  const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+  <SearchProvider runtime={runtime}>
+    <SearchPage adapter={useRouterSearchParams()} defaultType="listing" />
+  </SearchProvider>;
+  ```
+
+  No session, no workspace id, no auth client: every endpoint it calls is
+  `AllowAny`, so a catalogue renders for a visitor who will never sign in.
+
+  **The URL is the state.** Text, category, facet filters, ranges, geo, sort, page
+  size and the keyset cursor all live in the query string, under the backend's own
+  parameter names, and no component keeps a second copy. Copying the address into
+  another tab reproduces the page, Back removes exactly the last filter, and a
+  reload loses nothing — by construction rather than by discipline. Changing any
+  of them drops the keyset cursor, because `anchor` is a position inside one
+  ordered candidate set and carrying it across a filter change answers page 4 of
+  a different search. The router is a two-member seam (`SearchParamsAdapter`);
+  `./router` binds react-router's `useSearchParams`, and a Next.js app or a plain
+  `URLSearchParams` satisfies the same shape.
+
+  **Facets are drill-down, and the panel shows it.** Each is counted with its own
+  filter removed, so picking a value leaves its siblings with the counts you would
+  get by switching to them; closed sets keep their authored order, zeros included.
+  The server sends no option labels — they are keys in the category's feature
+  schema — so `categoryFeatures` is an explicit input and the captions resolve
+  through `@stapel/attributes-react`'s `formatFeatureValue`, the same formatter a
+  card uses.
+
+  **What the server admits, the screen repeats.** `exact_total: false` renders as
+  "about N", `facet_meta.approximate` says the counts are a sample, a skipped slug
+  shows "not counted" rather than `0`, and every `degraded[]` literal becomes a
+  line in a banner — including one this build has no wording for, which arrives
+  with its raw text. A failed search says "we could not run this search" with a
+  retry, and `error.400.search_window_exceeded` says "narrow the search"; neither
+  is ever spelled "nothing found".
+
+  `promoted` (DSA Art. 26) rides every item under every sort and reaches the card
+  slot whole, so a storefront's own `<ListingCard>` can still mark it; the P2B
+  Art. 5 ranking disclosure ships as a headless bag and a page, listing even the
+  parameters the configured engine cannot evaluate.
+
+  `./default` is the antd skin (`SearchPage`, `SearchResultsPane`,
+  `FacetPanelPane`, `RankingDisclosurePane`); the main entry carries no antd and
+  no router.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/i18n/ru.d.ts

@@ -7,7 +7,7 @@ export { searchErrorBundleRu } from "./generated/errors.ru.gen.js";
  * entry does not import this module — gated by size-limit + the bundle-purity
  * test).
  *
- * This is the storefront's DEFAULT language (darom-storefront verdict F1:
+ * This is the storefront's DEFAULT language (storefront spec verdict F1:
  * ru-first), which is why it is the fullest of the three bundles and why the
  * wording is checked against what a marketplace visitor is actually being
  * told — "counts are approximate" has to sound like an explanation, not an

package/dist/i18n/ru.js

@@ -7,7 +7,7 @@ export { searchErrorBundleRu } from "./generated/errors.ru.gen.js";
  * entry does not import this module — gated by size-limit + the bundle-purity
  * test).
  *
- * This is the storefront's DEFAULT language (darom-storefront verdict F1:
+ * This is the storefront's DEFAULT language (storefront spec verdict F1:
  * ru-first), which is why it is the fullest of the three bundles and why the
  * wording is checked against what a marketplace visitor is actually being
  * told — "counts are approximate" has to sound like an explanation, not an

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/search-react 0.1.0
+# @stapel/search-react 0.2.0
 
 Headless React flow pair for stapel-search (contract >=0.1 <0.2) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.1 <0.2"

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/search-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "entries": [
     {
       "id": "search.results",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -50,13 +50,6 @@
     "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",
@@ -106,11 +99,6 @@
   },
   "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",
@@ -122,12 +110,24 @@
     "react-router": "^7.18.1",
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@stapel/attributes-react": "^0.2.0",
+    "@stapel/core": "^0.15.0",
+    "@stapel/showcase": "^0.2.0",
+    "@stapel/tokens": "^0.5.0",
+    "@stapel/tokens-antd": "^0.5.0"
   },
   "engines": {
     "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "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"
   }
-}
+}

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.1.0",
+  "version": "0.2.0",
   "defined": [],
   "flows": []
 }