@stapel/search-react 0.1.0

package/dist/model/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/model/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAYlD,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,aAAa,GAAG,IAAI,CAC3C,CAAC;AAErB,eAAO,MAAM,gBAAgB,EAAE,MAAM,aAA8B,CAAC;AAEpE,eAAO,MAAM,YAAY,EAAE,MAAM,SAAsB,CAAC;AAExD,eAAO,MAAM,kBAAkB,EAAE,MAAM,SAAS,GAAG,IAAuB,CAAC;AAE3E,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAC,UAAU,CACzD,CAAC"}

package/dist/model/context.js

@@ -0,0 +1,16 @@
+import { createModuleContext } from "@stapel/core";
+/**
+ * The wired SearchRuntime shared through React context by
+ * `<SearchProvider>`. Hooks in `model/` and `headless/` read the singletons
+ * from here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit = createModuleContext("Search");
+export const SearchRuntimeContext = kit.RuntimeContext;
+export const useSearchRuntime = kit.useRuntime;
+export const useSearchApi = kit.useApi;
+export const useSearchAnalytics = kit.useAnalytics;
+/** @internal Re-exported as `<SearchProvider>` from `headless/`. */
+export const ModuleProvider = kit.Provider;
+//# sourceMappingURL=context.js.map

package/dist/model/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/model/context.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKnD;;;;;;GAMG;AACH,MAAM,GAAG,GACP,mBAAmB,CAAgB,QAAQ,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,oBAAoB,GAC/B,GAAG,CAAC,cAAc,CAAC;AAErB,MAAM,CAAC,MAAM,gBAAgB,GAAwB,GAAG,CAAC,UAAU,CAAC;AAEpE,MAAM,CAAC,MAAM,YAAY,GAAoB,GAAG,CAAC,MAAM,CAAC;AAExD,MAAM,CAAC,MAAM,kBAAkB,GAA2B,GAAG,CAAC,YAAY,CAAC;AAE3E,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GACzB,GAAG,CAAC,QAAQ,CAAC"}

package/dist/model/queries.d.ts

@@ -0,0 +1,48 @@
+import type { UseQueryResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import type { RankingResponse, SearchQueryState, SearchResponse } from "../api/types.js";
+/**
+ * Read hooks over the search API (frontend-standard §2). Keys are namespaced
+ * (see `searchQueryKeys`).
+ *
+ * NOT SESSION-GATED, and that is the documented exception rather than an
+ * omission. Sibling pairs gate every read on `useActiveSessionReady` because
+ * their endpoints need a principal; these three are `AllowAny`, and core's own
+ * doc comment carves out exactly this case ("or be unconditionally safe
+ * pre-session, e.g. a public GET"). Gating them would make a storefront's
+ * catalogue wait for a login bootstrap that a visitor who will never sign in
+ * has no stake in — a blank shop front for the length of a token refresh.
+ */
+/**
+ * One keyset page of results for a search state.
+ *
+ * `placeholderData: keepPreviousData`, and it is not a nicety. Facets are
+ * DRILL-DOWN: the whole point of the panel is that choosing a value leaves its
+ * siblings with the counts you would get by switching to them. A panel that
+ * blanks to a spinner between every click cannot show that — the person sees
+ * the numbers vanish and reappear, which reads exactly like the naive facets
+ * this contract avoids. The previous answer therefore stays on screen while
+ * the next one is in flight, with `isFetching` telling a skin 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.
+ *
+ * `retry: false`: the refusals here are VERDICTS about the request, not blips
+ * — an unknown sort, a malformed range, a cursor past `MAX_RESULT_WINDOW`.
+ * Retrying a 400 three times only delays the moment the page can say which
+ * one it was. A real outage answers 503 and is retried by the person, through
+ * the bag's `refetch` (the spec's §7.4 negative leg: "we could not ask" plus a
+ * retry, never "nothing found").
+ */
+export declare function useSearchQuery(state: SearchQueryState, options?: {
+    readonly enabled?: boolean;
+}): UseQueryResult<SearchResponse, StapelApiError>;
+/**
+ * The P2B Art. 5 ranking disclosure.
+ *
+ * `staleTime: Infinity`: the scorer registry changes when somebody deploys,
+ * not while a person reads the page it explains.
+ */
+export declare function useRankingDisclosure(type?: string): UseQueryResult<RankingResponse, StapelApiError>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/model/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/model/queries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACf,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAUhD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CAAC,eAAe,EAAE,cAAc,CAAC,CAQjD"}

package/dist/model/queries.js

@@ -0,0 +1,65 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { searchQueryParams } from "../api/searchApi.js";
+import { useSearchApi } from "./context.js";
+import { searchQueryKeys } from "./queryKeys.js";
+/**
+ * Read hooks over the search API (frontend-standard §2). Keys are namespaced
+ * (see `searchQueryKeys`).
+ *
+ * NOT SESSION-GATED, and that is the documented exception rather than an
+ * omission. Sibling pairs gate every read on `useActiveSessionReady` because
+ * their endpoints need a principal; these three are `AllowAny`, and core's own
+ * doc comment carves out exactly this case ("or be unconditionally safe
+ * pre-session, e.g. a public GET"). Gating them would make a storefront's
+ * catalogue wait for a login bootstrap that a visitor who will never sign in
+ * has no stake in — a blank shop front for the length of a token refresh.
+ */
+/**
+ * One keyset page of results for a search state.
+ *
+ * `placeholderData: keepPreviousData`, and it is not a nicety. Facets are
+ * DRILL-DOWN: the whole point of the panel is that choosing a value leaves its
+ * siblings with the counts you would get by switching to them. A panel that
+ * blanks to a spinner between every click cannot show that — the person sees
+ * the numbers vanish and reappear, which reads exactly like the naive facets
+ * this contract avoids. The previous answer therefore stays on screen while
+ * the next one is in flight, with `isFetching` telling a skin 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.
+ *
+ * `retry: false`: the refusals here are VERDICTS about the request, not blips
+ * — an unknown sort, a malformed range, a cursor past `MAX_RESULT_WINDOW`.
+ * Retrying a 400 three times only delays the moment the page can say which
+ * one it was. A real outage answers 503 and is retried by the person, through
+ * the bag's `refetch` (the spec's §7.4 negative leg: "we could not ask" plus a
+ * retry, never "nothing found").
+ */
+export function useSearchQuery(state, options) {
+    const api = useSearchApi();
+    const params = searchQueryParams(state);
+    return useQuery({
+        queryKey: searchQueryKeys.query(params),
+        queryFn: ({ signal }) => api.query(state, { signal }),
+        enabled: (options?.enabled ?? true) && state.type.length > 0,
+        placeholderData: keepPreviousData,
+        retry: false,
+    });
+}
+/**
+ * The P2B Art. 5 ranking disclosure.
+ *
+ * `staleTime: Infinity`: the scorer registry changes when somebody deploys,
+ * not while a person reads the page it explains.
+ */
+export function useRankingDisclosure(type) {
+    const api = useSearchApi();
+    return useQuery({
+        queryKey: searchQueryKeys.ranking(type),
+        queryFn: ({ signal }) => api.ranking(type, { signal }),
+        staleTime: Number.POSITIVE_INFINITY,
+        retry: false,
+    });
+}
+//# sourceMappingURL=queries.js.map

package/dist/model/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/model/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAMxD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAuB,EACvB,OAAwC;IAExC,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,QAAQ,CAAC;QACd,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC;QACvC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC;QACrD,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAC5D,eAAe,EAAE,gBAAgB;QACjC,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAa;IAEb,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,OAAO,QAAQ,CAAC;QACd,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC;QACvC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC;QACtD,SAAS,EAAE,MAAM,CAAC,iBAAiB;QACnC,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/model/queryKeys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
+ * Everything under the `"search"` root so a host can invalidate the whole
+ * module or match a single read. Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ *
+ * THE KEY IS THE REQUEST. `query()` is keyed on the very object
+ * `searchQueryParams()` hands the client, not on a hand-picked subset — so a
+ * parameter that changes the URL and the request but not the key (the stale
+ * page bug: new filter, cached rows) cannot be written. TanStack hashes keys
+ * with sorted-key JSON, so two equal states hash equal regardless of the order
+ * the members were built in, and one cursor's page stays cached under its own
+ * key — which is what makes "back" instant.
+ */
+/** The wire query object a search read is keyed on. */
+export type SearchQueryKeyParams = Readonly<Record<string, string | number | boolean | undefined | readonly (string | number | boolean)[]>>;
+export declare const searchQueryKeys: {
+    readonly all: readonly ["search"];
+    query(params: SearchQueryKeyParams): readonly ["search", "query", SearchQueryKeyParams];
+    /** The P2B disclosure. `type` is optional on the endpoint; normalized to
+     * `null` so an absent type and an explicit `undefined` cannot cache twice. */
+    ranking(type?: string): readonly ["search", "ranking", string | null];
+    suggest(type: string, q: string, limit?: number): readonly ["search", "suggest", string, string, number | null];
+};
+//# sourceMappingURL=queryKeys.d.ts.map

package/dist/model/queryKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.d.ts","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CACzC,MAAM,CACJ,MAAM,EACJ,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,GACT,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CACzC,CACF,CAAC;AAIF,eAAO,MAAM,eAAe,EAAE;IAC5B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,CACH,MAAM,EAAE,oBAAoB,GAC3B,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC;IACtD;kFAC8E;IAC9E,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EACT,KAAK,CAAC,EAAE,MAAM,GACb,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAMlE,CAAC"}

package/dist/model/queryKeys.js

@@ -0,0 +1,22 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
+ * Everything under the `"search"` root so a host can invalidate the whole
+ * module or match a single read. Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ *
+ * THE KEY IS THE REQUEST. `query()` is keyed on the very object
+ * `searchQueryParams()` hands the client, not on a hand-picked subset — so a
+ * parameter that changes the URL and the request but not the key (the stale
+ * page bug: new filter, cached rows) cannot be written. TanStack hashes keys
+ * with sorted-key JSON, so two equal states hash equal regardless of the order
+ * the members were built in, and one cursor's page stays cached under its own
+ * key — which is what makes "back" instant.
+ */
+const ROOT = "search";
+export const searchQueryKeys = {
+    all: [ROOT],
+    query: (params) => [ROOT, "query", params],
+    ranking: (type) => [ROOT, "ranking", type ?? null],
+    suggest: (type, q, limit) => [ROOT, "suggest", type, q, limit ?? null],
+};
+//# sourceMappingURL=queryKeys.js.map

package/dist/model/queryKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryKeys.js","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,MAAM,IAAI,GAAG,QAAiB,CAAC;AAE/B,MAAM,CAAC,MAAM,eAAe,GAaxB;IACF,GAAG,EAAE,CAAC,IAAI,CAAC;IACX,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,IAAI,CAAC;IAClD,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC;CACvE,CAAC"}

package/dist/model/runtime.d.ts

@@ -0,0 +1,25 @@
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { SearchApi } from "../api/searchApi.js";
+/**
+ * The wired search runtime — core's `ModuleRuntime` bound to this pair's API
+ * (slim wave §21/S2). The returned `client` is what the host injects into
+ * core's `StapelConfigProvider` (as the default or the `"search"` module
+ * client), preserving the client-injection fork seam (frontend-standard §7.2).
+ *
+ * ANONYMOUS BY DESIGN. Every endpoint this pair calls is `AllowAny`, so a
+ * storefront's catalogue, category and search pages need nothing but:
+ *
+ * ```tsx
+ * const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+ * <SearchProvider runtime={runtime}>…</SearchProvider>
+ * ```
+ *
+ * No session, no workspace id, no auth client. When a session DOES exist the
+ * host's auth runtime supplies the token on the shared client and the same
+ * calls carry it — this pair neither requires nor waits for one, which is why
+ * its read hooks are deliberately not gated on `useActiveSessionReady`.
+ */
+export type SearchRuntime = ModuleRuntime<SearchApi>;
+export type CreateSearchRuntimeOptions = CreateModuleRuntimeOptions;
+export declare function createSearchRuntime(options: CreateSearchRuntimeOptions): SearchRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/model/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAErD,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,CAAC;AAEpE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,aAAa,CAEf"}

package/dist/model/runtime.js

@@ -0,0 +1,6 @@
+import { createModuleRuntime } from "@stapel/core";
+import { createSearchApi } from "../api/searchApi.js";
+export function createSearchRuntime(options) {
+    return createModuleRuntime((client) => createSearchApi(client), options);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/model/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AA0BtD,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,OAAO,mBAAmB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3E,CAAC"}

package/dist/nav/manifest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * This pair's contribution to the scripted-fullstack nav contract
+ * (`@stapel/core`'s `NavEntry`/`PackageNavManifest`). `scripts/gen-nav-
+ * manifest.mjs` reads `navEntries` below, stamps `package`/`version` from THIS
+ * package's own `package.json`, and emits
+ * `packages/search-react/nav-manifest.json` plus this package's slice of the
+ * root aggregate.
+ *
+ * Both entries declare `surface: "public"` EXPLICITLY. The derivation
+ * `requiresAuth ? "member" : "public"` would land on the same answer here, but
+ * the explicit declaration is what a public container can rely on: an entry
+ * that later gains `requiresAuth` for an unrelated reason must not silently
+ * fall out of the anonymous tree (`core/src/nav.ts`, `navEntrySurface`).
+ *
+ * `menuVisibleDefault: false` on both: the results page is a navigation TARGET
+ * reached from the header's search box, and the ranking disclosure is a
+ * footer link. Neither is a menu item — the same treatment `auth.login` gets.
+ */
+import type { NavEntry } from "@stapel/core";
+export declare const navEntries: readonly NavEntry[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/nav/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAgCzC,CAAC"}

package/dist/nav/manifest.js

@@ -0,0 +1,34 @@
+export const navEntries = [
+    {
+        id: "search.results",
+        labelKey: "search.results.title",
+        icon: "SearchOutlined",
+        route: { path: "/s" },
+        component: { export: "SearchPage", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: false,
+        requiresAuth: false,
+        surface: "public",
+        order: 10,
+    },
+    {
+        // The P2B Art. 5 disclosure as a PAGE, not a link to raw JSON. The
+        // regulation asks for a plain-language description of the main ranking
+        // parameters; `GET /search/api/v1/ranking` is the data behind it, and
+        // handing a visitor that JSON would satisfy nobody's reading of it. The
+        // route is `/ranking-disclosure`, not `/ranking`, so the SPA path cannot
+        // be mistaken — by a person or by `stapel/no-string-paths` — for the API
+        // operation of the same name.
+        id: "search.ranking",
+        labelKey: "search.ranking.title",
+        icon: "OrderedListOutlined",
+        route: { path: "/ranking-disclosure" },
+        component: { export: "RankingDisclosurePane", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: false,
+        requiresAuth: false,
+        surface: "public",
+        order: 11,
+    },
+];
+//# sourceMappingURL=manifest.js.map

package/dist/nav/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,EAAE,EAAE,gBAAgB;QACpB,QAAQ,EAAE,sBAAsB;QAChC,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QACrB,SAAS,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE;QACvD,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,mEAAmE;QACnE,uEAAuE;QACvE,sEAAsE;QACtE,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,8BAA8B;QAC9B,EAAE,EAAE,gBAAgB;QACpB,QAAQ,EAAE,sBAAsB;QAChC,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,EAAE,IAAI,EAAE,qBAAqB,EAAE;QACtC,SAAS,EAAE,EAAE,MAAM,EAAE,uBAAuB,EAAE,OAAO,EAAE,SAAS,EAAE;QAClE,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;CACF,CAAC"}

package/dist/router/index.d.ts

@@ -0,0 +1,10 @@
+import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
+/**
+ * react-router's `useSearchParams()` as a {@link SearchParamsAdapter}.
+ *
+ * `replace` is forwarded rather than dropped: a facet click PUSHES, so Back
+ * removes exactly that filter (the spec's §4.2 acceptance), while typing in
+ * the search box replaces so one history entry per keystroke never happens.
+ */
+export declare function useRouterSearchParams(): SearchParamsAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,mBAAmB,CAW3D"}

package/dist/router/index.js

@@ -0,0 +1,34 @@
+/**
+ * `@stapel/search-react/router` — the react-router v7 binding for the URL
+ * state, and nothing else.
+ *
+ * A SEPARATE entry point on purpose. URL state is a router concern, and the
+ * pair does not own the host's router: a Next.js app, a hash router, or a
+ * server render that reads `new URL(request.url).searchParams` all satisfy
+ * `SearchParamsAdapter` without this file. Keeping the binding here means the
+ * main entry pulls no router at all (size-limit proves it), and a host that
+ * uses react-router gets the call it cannot make wrong:
+ *
+ * ```tsx
+ * <SearchStateProvider adapter={useRouterSearchParams()} defaultType="listing">
+ * ```
+ */
+import { useMemo } from "react";
+import { useSearchParams } from "react-router";
+/**
+ * react-router's `useSearchParams()` as a {@link SearchParamsAdapter}.
+ *
+ * `replace` is forwarded rather than dropped: a facet click PUSHES, so Back
+ * removes exactly that filter (the spec's §4.2 acceptance), while typing in
+ * the search box replaces so one history entry per keystroke never happens.
+ */
+export function useRouterSearchParams() {
+    const [params, setParams] = useSearchParams();
+    return useMemo(() => ({
+        params,
+        setParams: (next, options) => {
+            setParams(next, { replace: options?.replace ?? false });
+        },
+    }), [params, setParams]);
+}
+//# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,eAAe,EAAE,CAAC;IAC9C,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,MAAM;QACN,SAAS,EAAE,CAAC,IAAqB,EAAE,OAAwC,EAAE,EAAE;YAC7E,SAAS,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC;QAC1D,CAAC;KACF,CAAC,EACF,CAAC,MAAM,EAAE,SAAS,CAAC,CACpB,CAAC;AACJ,CAAC"}

package/dist/state/degradations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `degraded[]` — the backend declaring, per query, what the configured engine
+ * could not do. The UI's job is to say it, not to smooth it over: a result
+ * page that quietly drops "typo tolerance is off" is a page that looks like a
+ * complete answer and is not one.
+ *
+ * The literals are produced in `stapel-search/services.py::_degradations` plus
+ * whatever the backend and the facet counter contribute; the concatenation is
+ * NOT de-duplicated upstream, so `"typo_tolerance"` can genuinely arrive
+ * twice. {@link parseDegradations} de-duplicates by the raw literal.
+ *
+ * An unrecognised literal is kept, not dropped — the honest failure mode for
+ * "the backend degraded in a way this build predates" is a generic sentence
+ * with the literal beside it, not silence.
+ */
+import type { SearchDegradation, SearchDegradationKind } from "../api/types.js";
+/** i18n key per kind (`search.degraded.*`). */
+export declare function degradationMessageKey(kind: SearchDegradationKind): string;
+/** Parse and de-duplicate the envelope's `degraded[]`. */
+export declare function parseDegradations(degraded: readonly string[] | undefined): readonly SearchDegradation[];
+/**
+ * Does this set of degradations mean the RESULT COUNT is an estimate?
+ *
+ * Two independent signals say so and a skin must not have to know which:
+ * the envelope's own `exact_total: false`, and the `"exact_total"`
+ * degradation. They agree in practice; treating either as decisive is what
+ * keeps "≈1 200" from ever being rendered as "1 200".
+ */
+export declare function countIsEstimate(exactTotal: boolean, degradations: readonly SearchDegradation[]): boolean;
+//# sourceMappingURL=degradations.d.ts.map

package/dist/state/degradations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradations.d.ts","sourceRoot":"","sources":["../../src/state/degradations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAYhF,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAEzE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACtC,SAAS,iBAAiB,EAAE,CAwB9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,SAAS,iBAAiB,EAAE,GACzC,OAAO,CAET"}

package/dist/state/degradations.js

@@ -0,0 +1,52 @@
+const SCORER_PREFIX = "scorer:";
+const KNOWN = {
+    typo_tolerance: "typo_tolerance",
+    phrase_synonyms: "phrase_synonyms",
+    exact_total: "exact_total",
+    exact_facet_counts: "exact_facet_counts",
+    category_rollup: "category_rollup",
+};
+/** i18n key per kind (`search.degraded.*`). */
+export function degradationMessageKey(kind) {
+    return `search.degraded.${kind}`;
+}
+/** Parse and de-duplicate the envelope's `degraded[]`. */
+export function parseDegradations(degraded) {
+    if (degraded === undefined)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const raw of degraded) {
+        if (seen.has(raw))
+            continue;
+        seen.add(raw);
+        if (raw.startsWith(SCORER_PREFIX)) {
+            out.push({
+                kind: "scorer",
+                raw,
+                scorer: raw.slice(SCORER_PREFIX.length),
+                messageKey: degradationMessageKey("scorer"),
+            });
+            continue;
+        }
+        const kind = KNOWN[raw];
+        out.push({
+            kind: kind ?? "unknown",
+            raw,
+            messageKey: degradationMessageKey(kind ?? "unknown"),
+        });
+    }
+    return out;
+}
+/**
+ * Does this set of degradations mean the RESULT COUNT is an estimate?
+ *
+ * Two independent signals say so and a skin must not have to know which:
+ * the envelope's own `exact_total: false`, and the `"exact_total"`
+ * degradation. They agree in practice; treating either as decisive is what
+ * keeps "≈1 200" from ever being rendered as "1 200".
+ */
+export function countIsEstimate(exactTotal, degradations) {
+    return !exactTotal || degradations.some((d) => d.kind === "exact_total");
+}
+//# sourceMappingURL=degradations.js.map

package/dist/state/degradations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradations.js","sourceRoot":"","sources":["../../src/state/degradations.ts"],"names":[],"mappings":"AAiBA,MAAM,aAAa,GAAG,SAAS,CAAC;AAEhC,MAAM,KAAK,GAAoD;IAC7D,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAC1B,kBAAkB,EAAE,oBAAoB;IACxC,eAAe,EAAE,iBAAiB;CACnC,CAAC;AAEF,+CAA+C;AAC/C,MAAM,UAAU,qBAAqB,CAAC,IAA2B;IAC/D,OAAO,mBAAmB,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAC/B,QAAuC;IAEvC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CAAC;gBACP,IAAI,EAAE,QAAQ;gBACd,GAAG;gBACH,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC;gBACvC,UAAU,EAAE,qBAAqB,CAAC,QAAQ,CAAC;aAC5C,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,IAAI,IAAI,SAAS;YACvB,GAAG;YACH,UAAU,EAAE,qBAAqB,CAAC,IAAI,IAAI,SAAS,CAAC;SACrD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAmB,EACnB,YAA0C;IAE1C,OAAO,CAAC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC;AAC3E,CAAC"}

package/dist/state/facets.d.ts

@@ -0,0 +1,68 @@
+import type { FeatureDef } from "@stapel/attributes-react";
+import type { FacetMeta, SearchQueryState } from "../api/types.js";
+/** One value of one facet. */
+export interface FacetOption {
+    readonly value: string;
+    /**
+     * How many candidates carry this value with the slug's own filter removed —
+     * or `null` when the slug was not counted (skipped, or facets off).
+     */
+    readonly count: number | null;
+    /** Resolved through the category schema; the raw value when there is none. */
+    readonly label: string;
+    readonly selected: boolean;
+}
+/** One facet slug, with its options. */
+export interface FacetGroup {
+    readonly slug: string;
+    /** The feature's display name (translated when it is a key), else the slug. */
+    readonly label: string;
+    /** The category-schema entry behind the slug, when the host supplied one. */
+    readonly feature: FeatureDef | undefined;
+    /** `false` when the server skipped this slug — counts are `null`. */
+    readonly counted: boolean;
+    readonly options: readonly FacetOption[];
+    /** The values currently chosen for this slug (URL state, not the response). */
+    readonly selected: readonly string[];
+}
+export interface BuildFacetGroupsInput {
+    /** The envelope's `facets`: `{slug: {value: count}}`. */
+    readonly facets: Readonly<Record<string, Readonly<Record<string, number>>>>;
+    readonly meta: FacetMeta;
+    /** Current URL state — the source of what is selected. */
+    readonly state: SearchQueryState;
+    /** The category's feature schema, for labels and option order. */
+    readonly categoryFeatures?: readonly FeatureDef[];
+    /** Translator for label keys. */
+    readonly t?: (key: string) => string;
+    /** BCP-47 tag, forwarded to `formatFeatureValue` for `date` options. */
+    readonly locale?: string;
+}
+/**
+ * A facet value as a person reads it, through
+ * `@stapel/attributes-react`'s `formatFeatureValue` — the same formatter the
+ * card and the 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 STRINGS (they are index terms), so the raw
+ * value is coerced back into the shape the type's formatter expects before
+ * being handed over. `select` is a list even for one value
+ * (`types/select/dto.py`), `date` is a Unix timestamp integer, numbers are
+ * numbers. A type the formatter cannot read gives back the raw value — never
+ * an empty label, which would leave an unnameable checkbox on screen.
+ */
+export declare function facetOptionLabel(feature: FeatureDef | undefined, value: string, options?: {
+    readonly t?: (key: string) => string;
+    readonly locale?: string;
+}): string;
+/**
+ * Fold the response's counts, the URL's selections and the category schema
+ * into the panel's groups.
+ *
+ * Groups appear for every counted slug, every skipped slug, and every slug the
+ * 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.
+ */
+export declare function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGroup[];
+//# sourceMappingURL=facets.d.ts.map

package/dist/state/facets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facets.d.ts","sourceRoot":"","sources":["../../src/state/facets.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,iCAAiC;IACjC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3E,MAAM,CAkCR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,SAAS,UAAU,EAAE,CA2DpF"}