@stapel/search-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @stapel/search-react

package/MODULE.md

@@ -0,0 +1,203 @@
+# @stapel/search-react — module guide
+
+The human companion to the generated `llms.txt` (agent context) and
+`manifest.json` (machine catalog). `README.md` is the how-to; this is the
+why-it-is-shaped-this-way.
+
+Built against **stapel-search 0.1.0** (contract pin
+`352cce979cee11936a8c822212fe87e377dd08cf`).
+
+## Layers
+
+- **api/** — `createSearchApi(client)`, one method per endpoint a storefront may
+  call (`query`, `suggest`, `ranking`), over the generated
+  `components["schemas"]` from this pair's own package-local
+  `api/generated/schema.ts` (`pnpm gen:api` ← stapel-search `docs/schema.json`).
+  `searchQueryParams(state)` is exported from here because it is *also* what the
+  query key is built from — see "the key is the request" below.
+- **state/** — the pure layer, and the biggest one: the URL codec
+  (`urlState.ts`), the `degraded[]` parser, and the facet model. No React, no
+  router, no fetch, which is what makes the round trip testable in both
+  directions without a DOM.
+- **model/** — `searchQueryKeys` (one factory, `["search"]` namespace),
+  `createSearchRuntime`, context/hooks, and the two read hooks.
+- **headless/** — `SearchProvider`, `SearchStateProvider`, `SearchResults`,
+  `FacetPanel`, `RankingDisclosure`.
+- **i18n/** — the en floor + generated backend error bundles; `ru`/`es` as their
+  own subpaths. `ru` is the storefront's default language (storefront spec verdict F1).
+- **default/** — the antd skin, a separate entry point.
+- **router/** — the react-router binding, a third entry point (see below).
+- **nav/** — two public entries: `/s` and `/ranking-disclosure`.
+
+There is **no `flows/` layer**: stapel-search annotates no `@flow_step`, and a
+search is not a multi-step flow (spec §8.1 — `flows/` only where one exists).
+
+## Why the URL codec is the centre of the package
+
+A search that cannot be shared is not a search — the acceptance criteria the
+spec sets (§4.2) are all about a link: copy it into another tab and get the same
+page, press Back and lose exactly the last filter, reload and lose nothing.
+
+Every one of those follows from a single decision: **the query string is the
+only copy of the state.** No component holds a duplicate, so there is nothing to
+keep in sync. `SearchStateProvider` parses on every render from the adapter's
+`URLSearchParams` and writes back through `writeSearchState`; the components
+below it read a bag and call mutators.
+
+Two consequences worth stating because they are easy to get wrong:
+
+1. **The parameter names are the backend's**, not a prettier set of our own. A
+   browser URL is then the API query string — a support ticket that pastes a
+   link is a request anyone can replay with curl — and there is no translation
+   table to drift.
+2. **Push vs replace is deliberate.** A filter change PUSHES (that is what makes
+   Back remove exactly one filter); typing in the search box and changing the
+   page size REPLACE (one history entry per keystroke would make Back useless).
+   The adapter forwards the flag; an adapter that ignores it breaks the Back
+   button, which is why the seam has it rather than hiding it.
+
+### The cursor is dropped by every change that is not a page move
+
+`anchor` is `{v, k, o}` base64url-encoded — a position inside ONE ordered
+candidate set, over the active sort. Carried across a filter or sort change the
+server either refuses it (`error.400.search_bad_cursor`) or honours it against a
+different set and answers page 4 of something nobody asked for.
+
+So `patchSearchState` drops `anchor`/`direction` unless the patch itself sets
+them, and every mutator in the provider goes through it. "Changing a filter
+returns you to the first page" is a property of the state machine, not a rule
+each call site remembers.
+
+## Why `@stapel/core` gained repeatable query parameters
+
+`f.<slug>` is read with `getlist` server-side: repeating the key is the OR
+within a slug (`stapel-search/query.py`). Core's client built its query string
+with `URLSearchParams.set`, which cannot express that — a second value silently
+replaced the first, and the only alternative was for this pair to hand-build its
+own URL. That would have been a second query encoder sitting next to core's,
+outside its escaping and outside `stapel/no-string-paths`.
+
+Core 0.15.0 therefore accepts an ARRAY value and `append`s it, in order; an
+empty array contributes nothing, exactly like `undefined` ("no filter" and "a
+filter with no values" must not produce different URLs). This pair's peer floor
+is `>=0.15.0` for that reason and no other — the symbol set is unchanged, so
+`check:peer-floors` could not have caught an understated floor here.
+
+## The key is the request
+
+`searchQueryKeys.query()` is keyed on the very object `searchQueryParams()`
+hands the client. A key built from a hand-picked subset is how a parameter comes
+to change the request but not the key — new filter, cached rows. TanStack hashes
+with sorted-key JSON, so equal states hash equal regardless of construction
+order, and each cursor's page stays cached under its own key, which is what
+makes Back instant.
+
+## `keepPreviousData`, and why it is a correctness choice here
+
+Facets are drill-down: the point of the panel is that choosing a value leaves
+its siblings showing what you would get by switching to them. A panel that
+blanks to a spinner between clicks cannot show that — the numbers vanish and
+reappear, which reads exactly like the naive facets this contract avoids. So the
+previous answer stays on screen while the next is in flight, with `isFetching`
+for a skin that wants to dim it.
+
+The load discipline is intact: the first load has nothing to keep and is
+`loading`, and a failure still lands as `failed` rather than leaving stale rows
+pretending to be current.
+
+## The two slot seams
+
+L2 pairs do not import each other, so the two things a storefront must supply
+are props, not dependencies (spec §6.2 items 1–2):
+
+- **`renderCard`** — `<ListingCard>` from `@stapel/listings-react/default`. The
+  generic card here is a working default over a documented set of conventional
+  `card` fields (`title`, `price`, `currency`, `location`, `image_url`), because
+  `SearchItem.card` is deliberately free-form: "stored row fields, so a result
+  page costs one query".
+- **`categoryFeatures`** — the category's feature schema, from
+  `categories-react`. The server sends `{value: count}` and no labels; the
+  captions are translation keys in that schema.
+
+Facet values are rendered through `@stapel/attributes-react`'s
+`formatFeatureValue` — the same formatter a card and a spec table use, so a
+value cannot read one way in the filter and another way in the result. The wire
+carries facet values as index TERMS (strings), so `facetOptionLabel` coerces
+back into the shape each type's formatter expects: `select` is a list even for
+one value, `date` is a Unix timestamp integer, `int`/`float` are numbers.
+
+## Honesty flags are not decoration
+
+Four independent signals, all surfaced:
+
+| Signal | Where it comes from | What must not happen |
+|---|---|---|
+| `exact_total` | envelope | rendering an estimate as an exact count |
+| `facet_meta.approximate` | candidate set over `FACET_CANDIDATE_CAP` | a precise-looking number |
+| `facet_meta.skipped` | plan slugs dropped at `MAX_FACET_FIELDS` | a `0` where nothing was counted |
+| `degraded[]` | `_degradations` + backend + facet counter | silence |
+
+`degraded[]` is de-duplicated on parse, because the backend concatenates three
+contributions without de-duplicating them (`services.py`) and the same literal
+can arrive twice. An unrecognised literal is kept with `kind: "unknown"` and
+shown with its raw text — a build that predates a new limitation should say so.
+
+## Where the refusals go
+
+`error.400.search_window_exceeded` gets its own branch in the results pane.
+Everything about it looks like an empty page — a 400, no rows — and it means the
+opposite: there are more results, they are just past `MAX_RESULT_WINDOW`. The
+sentence is "narrow the search".
+
+The views turn EVERY backend exception into `503
+error.503.search_backend_unavailable`, so a client never has to distinguish a
+500 from an outage: a dead engine is always "we could not ask", never "there is
+nothing here".
+
+## Notes on the contract, recorded rather than worked around
+
+1. **`docs/flows.json` is `{}`.** Every other module ships `[]`. The monorepo's
+   `gen-flows.mjs` requires an array and throws on an object, so this pair is
+   not wired into `gen:flows` at all — which costs nothing, because there are no
+   flows to generate. Upstream ask: emit `[]` for uniformity.
+2. **The schema declares no `enum`s.** `sort`, `direction` and `facets` have
+   their vocabularies in prose and in Python (`SORTS` is a setting a deployment
+   may extend). So `sort` is typed as `string`, `SEARCH_SORTS` is the shipped
+   list a control offers, and an unknown value is passed through for the server
+   to refuse by name — a client that reset it would rewrite a shared link's
+   meaning on load.
+3. **`info.title` is empty and `info.version` is `0.0.0`** in the schema. The
+   manifest's `backend.contract` comes from `pyproject.toml`, as everywhere else
+   in this repo; nothing reads the schema's version.
+4. **`prev_anchor` is absent when the previous page is the first one.** The
+   cursor's absence is what "page 1" means under keyset paging, so walking back
+   clears `anchor` rather than inventing one.
+5. **`minLon > maxLon` in a bbox is legal** — the box crosses the antimeridian.
+   The codec does not normalize it.
+
+## Tests
+
+103, in 12 files. The ones that exist for a named reason:
+
+- `urlState.test.ts` — the round trip in both directions, the repeated `f.`
+  key, the antimeridian bbox, unknown parameters preserved, and the cursor
+  dropped by every non-paging change.
+- `urlSync.test.tsx` — the same properties through the real provider and skin:
+  a facet click lands in the URL and in the next request, the history gains one
+  entry per filter (so Back removes one), a shared link reproduces the request.
+- `facets.test.tsx` — drill-down siblings keep their counts, closed sets keep
+  their declared order, a skipped slug says "not counted", labels resolve
+  through the category schema.
+- `results.test.tsx` — the four load outcomes, the window refusal as its own
+  sentence, the estimated-vs-exact count, and `promoted` under every one of the
+  five sorts.
+- `pagination.test.tsx` — cursor forward and back with `direction`, both
+  controls blocked WITH a reason, and the panel not blanking between clicks.
+- `degraded.test.tsx` — every literal parsed, duplicates collapsed, unknown
+  kept.
+- `contract.test.ts` — every operation lands on a path the backend declares,
+  every query parameter is one it declares, and `f.<slug>` is repeated rather
+  than comma-joined.
+- `pair.test.ts` — nav ids unique and namespaced, `surface` explicit, every
+  component the manifest names actually exported, every `labelKey` in the
+  bundle.

package/README.md

@@ -0,0 +1,175 @@
+# @stapel/search-react
+
+The frontend pair for **stapel-search**: a storefront's catalogue, category and
+search pages, all three from one endpoint — with drill-down facets, geo, sorts,
+keyset paging, the DSA Art. 26 `promoted` marking and the P2B Art. 5 ranking
+disclosure.
+
+Business + state in the main entry, zero visual opinion; the antd skin lives
+behind `./default` and the react-router binding behind `./router`, so a host
+that renders its own visuals carries neither. Built on `@stapel/core` (typed
+client + `StapelApiError` envelope, `LoadState`, i18n engine, analytics seam,
+TanStack Query) and `@stapel/attributes-react` (facet value display).
+
+## Install
+
+```
+pnpm add @stapel/search-react @stapel/core @stapel/attributes-react @tanstack/react-query react
+# for the default skin:
+pnpm add antd @stapel/tokens-antd
+# for the react-router URL binding:
+pnpm add react-router
+```
+
+## A search page, in eight lines
+
+**No session, no workspace id, no auth client** — every endpoint this pair calls
+is `AllowAny`, so a catalogue renders for a visitor who will never sign in:
+
+```tsx
+import { createSearchRuntime, SearchProvider } from "@stapel/search-react";
+import { SearchPage } from "@stapel/search-react/default";
+import { useRouterSearchParams } from "@stapel/search-react/router";
+
+const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+
+export function SearchRoute() {
+  return (
+    <SearchProvider runtime={runtime}>
+      <SearchPage adapter={useRouterSearchParams()} defaultType="listing" />
+    </SearchProvider>
+  );
+}
+```
+
+In an app that already has a session, put the search client on core's provider
+alongside the others and keep one client per module:
+
+```tsx
+<StapelProvider client={authRuntime.client} clients={{ search: runtime.client }} i18n={i18n}>
+  <SearchProvider runtime={runtime}>{app}</SearchProvider>
+</StapelProvider>
+```
+
+## 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**, so a browser URL *is* the API query string and a pasted link is a
+request anyone can replay with curl:
+
+```
+/s?type=listing&q=drill&f.brand=bosch&f.brand=makita&r.price=100..500
+  &lat=55.75&lon=37.62&radius_km=25&sort=price_asc&anchor=…
+```
+
+No component keeps a second copy, which is what makes all three of these
+properties hold by construction rather than by discipline:
+
+| You do this | This happens |
+|---|---|
+| copy the address into another tab | the same results |
+| press Back | exactly the last filter comes off |
+| reload | nothing is lost |
+| change a filter while on page 4 | you land on page 1 — the cursor is dropped |
+
+That last row is not a nicety. `anchor` encodes a position inside **one**
+ordered candidate set; carried across a filter change it either gets refused or,
+worse, honoured against a different set. `patchSearchState` drops it for every
+change that is not itself a page move, so no call site has to remember.
+
+**Any router, or none.** `SearchStateProvider` takes a `SearchParamsAdapter` —
+two members, shaped exactly like react-router's `useSearchParams()`. `./router`
+ships that binding; a Next.js app, a hash router or a plain `URLSearchParams` in
+a test satisfy the same seam.
+
+## Facets are drill-down, and the panel says so
+
+Each facet is counted over the candidates **with its own filter removed**
+(`stapel-search/facets.py`). So picking *Bosch* does not zero *Makita*: its
+count stays what you would get by switching to it. Closed option sets arrive
+exhaustively, zeros included, and keep their authored order.
+
+The server does not send option **labels** — they are translation keys in the
+category's feature schema. Hand that schema in and the options read as words:
+
+```tsx
+<FacetPanelPane categoryFeatures={features} />   // from categories-react
+```
+
+Without it, options read as raw index terms. Never as blanks.
+
+## What the server admits, the screen repeats
+
+| The envelope says | The page says |
+|---|---|
+| `exact_total: false` | "About 1 200 results", never "1 200" |
+| `facet_meta.approximate` | "counts are approximate — too many candidates to count them all" |
+| `facet_meta.skipped: [...]` | those slugs are named, and their options show **"not counted"** — never `0` |
+| `degraded: ["category_rollup", …]` | a banner, one line per degradation, the scorer named |
+| a `degraded` literal this build predates | the generic sentence **plus the raw literal** |
+
+A silent `0` where a facet was not counted is the same defect class as
+`data ?? []`: a number that looks like an answer and is not one.
+
+## A failed search is never "nothing found"
+
+A result read has **four** outcomes and the skin says a different thing for
+each — `matchList`'s arms are all required, so forgetting one does not compile:
+
+| What happened | What the person sees |
+|---|---|
+| in flight | a skeleton |
+| 200, no hits | "nothing matches this search" |
+| 5xx / network | "we could not run this search" + retry |
+| 400 `search_window_exceeded` | "narrow the search instead of paging further" |
+
+The last row matters on its own: the window refusal arrives as a 400 with no
+rows, which is exactly the shape that renders as an empty page if nobody
+branches on it.
+
+## `promoted` is not optional
+
+DSA Art. 26 marking rides **every** item under **every** sort. The card slot
+receives the whole item, and the default card renders the tag:
+
+```tsx
+<SearchResultsPane renderCard={(item) => <ListingCard item={item} />} />
+```
+
+A storefront replaces the generic card with its own (`<ListingCard>` from
+`@stapel/listings-react/default`); what it may not do is drop the marking. The
+companion half — *why these results are in this order* — is the P2B Art. 5
+disclosure, generated from the backend's scorer registry and shipped as both a
+headless bag and a page (`<RankingDisclosurePane>`), including the parameters
+the configured engine cannot evaluate.
+
+## Surface
+
+| Layer | Exports |
+|---|---|
+| api | `createSearchApi`, `searchQueryParams`, `SEARCH_SORTS`, wire types |
+| state (pure) | `parseSearchState`, `writeSearchState`, `patchSearchState`, `toggleFilterValue`, `setFilterValues`, `setRangeValue`, `clearFilters`, `activeFilterCount`, `parseDegradations`, `countIsEstimate`, `buildFacetGroups`, `facetOptionLabel` |
+| model | `createSearchRuntime`, `searchQueryKeys`, `useSearchQuery`, `useRankingDisclosure` |
+| headless | `SearchProvider`, `SearchStateProvider`/`useSearchState`, `SearchResults`, `FacetPanel`, `RankingDisclosure` |
+| `./default` | `SearchPage`, `SearchResultsPane`, `FacetPanelPane`, `RankingDisclosurePane`, `SearchResultCard`, `DegradationNotice`, `UrlIssueNotice`, `SortSelect`, `SearchSkinTheme` |
+| `./router` | `useRouterSearchParams` |
+| i18n | `registerSearchI18n` (+ `./i18n/ru`, `./i18n/es`) |
+| errors | `SEARCH_ERRORS`, `explainSearchError`, `SEARCH_WINDOW_EXCEEDED`, `SEARCH_BACKEND_UNAVAILABLE` |
+
+## Not in this version
+
+- **`suggest`** — the endpoint is typed and callable (`api.suggest(...)`), but
+  there is no hook and no autocomplete widget: debounce and keyboard handling
+  are their own piece of work.
+- **`health` / `reindex`** — index-operator endpoints (`IsNotAnonymousUser` +
+  `can_manage`). Not a storefront's surface, so not on this pair's client.
+- **a map** — geo is complete on the wire (`lat`/`lon`/`radius_km`, `bbox`,
+  `sort=distance`) and the state layer carries all of it; drawing a map is a
+  tile provider, a key and a CSP change.
+- **saved searches.**
+
+## More
+
+`MODULE.md` — why it is shaped this way. `llms.txt` — the agent-facing
+description, generated and drift-gated.