@stapel/search-react 0.1.0

package/src/model/queries.ts

@@ -0,0 +1,79 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import type { UseQueryResult } from "@tanstack/react-query";
+import type { StapelApiError } from "@stapel/core";
+import { searchQueryParams } from "../api/searchApi.js";
+import type {
+  RankingResponse,
+  SearchQueryState,
+  SearchResponse,
+} from "../api/types.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: SearchQueryState,
+  options?: { readonly enabled?: boolean }
+): UseQueryResult<SearchResponse, StapelApiError> {
+  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?: string
+): UseQueryResult<RankingResponse, StapelApiError> {
+  const api = useSearchApi();
+  return useQuery({
+    queryKey: searchQueryKeys.ranking(type),
+    queryFn: ({ signal }) => api.ranking(type, { signal }),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false,
+  });
+}

package/src/model/queryKeys.ts

@@ -0,0 +1,48 @@
+/**
+ * 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)[]
+  >
+>;
+
+const ROOT = "search" as const;
+
+export 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];
+} = {
+  all: [ROOT],
+  query: (params) => [ROOT, "query", params],
+  ranking: (type) => [ROOT, "ranking", type ?? null],
+  suggest: (type, q, limit) => [ROOT, "suggest", type, q, limit ?? null],
+};

package/src/model/runtime.ts

@@ -0,0 +1,33 @@
+import { createModuleRuntime } from "@stapel/core";
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import { createSearchApi } from "../api/searchApi.js";
+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 function createSearchRuntime(
+  options: CreateSearchRuntimeOptions
+): SearchRuntime {
+  return createModuleRuntime((client) => createSearchApi(client), options);
+}

package/src/nav/manifest.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 const navEntries: readonly NavEntry[] = [
+  {
+    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,
+  },
+];

package/src/router/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `@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";
+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 function useRouterSearchParams(): SearchParamsAdapter {
+  const [params, setParams] = useSearchParams();
+  return useMemo(
+    () => ({
+      params,
+      setParams: (next: URLSearchParams, options?: { readonly replace?: boolean }) => {
+        setParams(next, { replace: options?.replace ?? false });
+      },
+    }),
+    [params, setParams]
+  );
+}

package/src/state/degradations.ts

@@ -0,0 +1,75 @@
+/**
+ * `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";
+
+const SCORER_PREFIX = "scorer:";
+
+const KNOWN: Readonly<Record<string, SearchDegradationKind>> = {
+  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: SearchDegradationKind): string {
+  return `search.degraded.${kind}`;
+}
+
+/** Parse and de-duplicate the envelope's `degraded[]`. */
+export function parseDegradations(
+  degraded: readonly string[] | undefined
+): readonly SearchDegradation[] {
+  if (degraded === undefined) return [];
+  const seen = new Set<string>();
+  const out: SearchDegradation[] = [];
+  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: boolean,
+  degradations: readonly SearchDegradation[]
+): boolean {
+  return !exactTotal || degradations.some((d) => d.kind === "exact_total");
+}

package/src/state/facets.ts

@@ -0,0 +1,219 @@
+/**
+ * The facet panel's data model — and the two things about stapel-search's
+ * facets a panel is obliged to show.
+ *
+ * 1. **They are DRILL-DOWN.** Every facet is counted over the candidate set
+ *    with ITS OWN filter removed (`stapel-search/facets.py`). So picking
+ *    "Bosch" does not zero its neighbours: the other brands keep the counts
+ *    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. **The server does not send option LABELS** (`facets.py` returns
+ *    `{value: count}` and nothing else). The labels are in the category's
+ *    feature schema, which is why {@link buildFacetGroups} takes
+ *    `categoryFeatures` — the second slot-seam of the pair, filled by the
+ *    container from `categories-react` (spec §6.2 item 2). Without it the
+ *    panel still works and shows raw values; it does not invent labels.
+ *
+ * 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.
+ */
+import { featureConfig, featureName, featureType, formatFeatureValue } from "@stapel/attributes-react";
+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;
+}
+
+function translate(t: ((key: string) => string) | undefined, key: string): string {
+  if (t === undefined) return key;
+  const resolved = t(key);
+  return resolved.length > 0 ? resolved : key;
+}
+
+/**
+ * The declared option ORDER for a closed set, if the schema declares one.
+ *
+ * Closed sets arrive zero-filled from the server (`fill_zero_options`), and a
+ * closed set is a list somebody authored: showing it in count order reshuffles
+ * a size chart on every click. Open sets have no authored order, so they fall
+ * back to count-descending.
+ */
+function declaredOptionValues(feature: FeatureDef | undefined): readonly string[] {
+  if (feature === undefined) return [];
+  const raw = featureConfig(feature)["options"];
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const option of raw) {
+    if (option !== null && typeof option === "object") {
+      const value = (option as { value?: unknown }).value;
+      if (value !== undefined && value !== null) out.push(String(value));
+    } else if (typeof option === "string") {
+      out.push(option);
+    }
+  }
+  return out;
+}
+
+/**
+ * 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 function facetOptionLabel(
+  feature: FeatureDef | undefined,
+  value: string,
+  options?: { readonly t?: (key: string) => string; readonly locale?: string }
+): string {
+  if (feature === undefined) return value;
+  const type = featureType(feature);
+  if (type === undefined) return value;
+
+  let coerced: unknown = value;
+  switch (type) {
+    case "select":
+    case "hierarchical_select":
+      coerced = [value];
+      break;
+    case "int":
+    case "float":
+    case "date": {
+      const parsed = Number(value);
+      coerced = Number.isFinite(parsed) ? parsed : value;
+      break;
+    }
+    case "bool":
+      coerced = value === "true" || value === "1";
+      break;
+    default:
+      coerced = value;
+  }
+
+  const formatted = formatFeatureValue(
+    feature,
+    { type, value: coerced },
+    {
+      ...(options?.t !== undefined ? { t: options.t } : {}),
+      ...(options?.locale !== undefined ? { locale: options.locale } : {}),
+    }
+  );
+  return formatted !== undefined && formatted.length > 0 ? formatted : value;
+}
+
+/**
+ * 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 function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGroup[] {
+  const bySlug = new Map<string, FeatureDef>();
+  for (const feature of input.categoryFeatures ?? []) bySlug.set(feature.slug, feature);
+
+  const skipped = new Set(input.meta.skipped);
+  const slugs: string[] = [];
+  const seen = new Set<string>();
+  for (const slug of [
+    ...Object.keys(input.facets),
+    ...input.meta.skipped,
+    ...Object.keys(input.state.filters),
+  ]) {
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    slugs.push(slug);
+  }
+
+  return slugs.map((slug) => {
+    const feature = bySlug.get(slug);
+    const counts = input.facets[slug] ?? {};
+    const counted = !skipped.has(slug) && slug in input.facets;
+    const selected = input.state.filters[slug] ?? [];
+
+    const declared = declaredOptionValues(feature);
+    const values: string[] = [];
+    const push = (value: string): void => {
+      if (!values.includes(value)) values.push(value);
+    };
+    // Declared order first (closed sets), then whatever else the counter
+    // returned, then anything selected that neither of them mentioned.
+    for (const value of declared) if (value in counts) push(value);
+    const remaining = Object.keys(counts)
+      .filter((value) => !declared.includes(value))
+      .sort((a, b) => (counts[b] ?? 0) - (counts[a] ?? 0) || a.localeCompare(b));
+    for (const value of remaining) push(value);
+    for (const value of selected) push(value);
+
+    const labelOptions = {
+      ...(input.t !== undefined ? { t: input.t } : {}),
+      ...(input.locale !== undefined ? { locale: input.locale } : {}),
+    };
+
+    return {
+      slug,
+      label:
+        feature === undefined
+          ? slug
+          : translate(input.t, featureName(feature)),
+      feature,
+      counted,
+      selected,
+      options: values.map((value) => ({
+        value,
+        count: counted ? (counts[value] ?? 0) : null,
+        label: facetOptionLabel(feature, value, labelOptions),
+        selected: selected.includes(value),
+      })),
+    };
+  });
+}