@stapel/search-react 0.1.0

package/src/api/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Wire types for the stapel-search HTTP contract — **derived from the
+ * generated OpenAPI surface** (frontend-standard §2/§3), never hand-maintained.
+ * The single source of truth is `components["schemas"]` from this pair's own
+ * package-LOCAL generated schema (`./generated/schema.js`, produced by
+ * `pnpm gen:api` from stapel-search's OWN `docs/schema.json`).
+ *
+ * Where drf-spectacular under-describes the runtime, this file adds a small
+ * documented correction and states what the generator lost.
+ */
+import type { components } from "./generated/schema.js";
+
+/** The generated schema table — the one source of truth for wire shapes. */
+export type Schemas = components["schemas"];
+
+/** `GET /query` 200 — the whole envelope. */
+export type SearchResponse = Schemas["SearchResponse"];
+
+/** One result row. `promoted` is present on EVERY item under EVERY sort — a
+ * mandatory marking (DSA Art. 26), not an optional field, which is why the
+ * card slot's contract carries it and why the default skin renders it. */
+export type SearchItem = Schemas["SearchItem"];
+
+/** The honesty block beside the counts: `approximate`, `candidates`,
+ * `counted`, `skipped`. Rendered, never swallowed (spec §4.2). */
+export type FacetMeta = Schemas["FacetMeta"];
+
+/** `GET /suggest` 200. */
+export type SuggestResponse = Schemas["SuggestResponse"];
+
+/** `GET /ranking` 200 — the P2B Art. 5 disclosure. */
+export type RankingResponse = Schemas["RankingResponse"];
+
+/** One ranking parameter of the disclosure. */
+export type Scorer = Schemas["Scorer"];
+
+/**
+ * The sorts stapel-search ships (`conf.py::DEFAULT_SORTS`).
+ *
+ * GENERATOR NOTE, and the reason `sort` is typed as a plain `string` below:
+ * `docs/schema.json` declares **no `enum`** on any query parameter — the sort
+ * vocabulary lives in the backend's `SORTS` setting, which a deployment may
+ * extend. So this list is what the shipped default offers a sort control, NOT
+ * a claim about what the server will accept. An unknown value is refused by
+ * the server with `error.400.search_unknown_sort`, naming the value; a client
+ * union that silently dropped it would turn a shareable link into an empty
+ * page.
+ */
+export const SEARCH_SORTS: readonly string[] = [
+  "relevance",
+  "newest",
+  "price_asc",
+  "price_desc",
+  "distance",
+];
+
+/** Which facets to count: the category's own plan (`"on"`/omitted), none
+ * (`"off"`), or an explicit slug list. */
+export type FacetSelection = "on" | "off" | readonly string[];
+
+/** One `r.<slug>` range. Either end may be absent — `..500` and `100..` are
+ * both legal, and both ends absent means "no range at all". */
+export interface SearchRange {
+  readonly from?: string;
+  readonly to?: string;
+}
+
+/** A point plus an optional radius (`lat`/`lon`/`radius_km`). */
+export interface SearchGeoCenter {
+  readonly kind: "center";
+  readonly lat: number;
+  readonly lon: number;
+  readonly radiusKm?: number;
+}
+
+/**
+ * A bounding box (`bbox=minLat,minLon,maxLat,maxLon`). `minLon > maxLon` is
+ * LEGAL and means the box crosses the antimeridian — the codec must not
+ * "fix" it, and the backend explicitly allows it (`query.py`).
+ */
+export interface SearchGeoBox {
+  readonly kind: "bbox";
+  readonly minLat: number;
+  readonly minLon: number;
+  readonly maxLat: number;
+  readonly maxLon: number;
+}
+
+/** Either geo form. `bbox` wins server-side when both are sent, so the state
+ * model carries one or the other and never both. */
+export type SearchGeo = SearchGeoCenter | SearchGeoBox;
+
+/**
+ * The full query state — everything the URL carries, in one value.
+ *
+ * `type` is the only required parameter of the endpoint (`error.400
+ * .search_unknown_doc_type` names it when absent or unregistered).
+ */
+export interface SearchQueryState {
+  /** Registered doc type. One type per query; federated search is not in v1. */
+  readonly type: string;
+  /** Free text. `""` means "no text", which is a valid search (browse). */
+  readonly q: string;
+  /** Language of the query: picks the analyzer AND narrows the corpus. */
+  readonly lang?: string;
+  /** `root/leaf` path. A PREFIX filter — a parent finds its descendants. */
+  readonly category?: string;
+  /** Opaque owner key — the seller's own listings. */
+  readonly owner?: string;
+  /** `f.<slug>` → the chosen values. Repeat = OR within a slug; different
+   * slugs AND together. An empty array is the same as no entry. */
+  readonly filters: Readonly<Record<string, readonly string[]>>;
+  /** `r.<slug>` → `from..to`. */
+  readonly ranges: Readonly<Record<string, SearchRange>>;
+  readonly geo?: SearchGeo;
+  /** Omitted lets the server choose (`relevance` with text, else `newest`). */
+  readonly sort?: string;
+  readonly facets?: FacetSelection;
+  /** Opaque keyset cursor from a previous answer. */
+  readonly anchor?: string;
+  readonly direction?: "next" | "prev";
+  readonly limit?: number;
+}
+
+/** Request shape for `GET /suggest` (typed, but deliberately not hooked —
+ * see `searchApi.ts`). */
+export interface SuggestParams {
+  readonly type: string;
+  readonly q?: string;
+  readonly limit?: number;
+}
+
+/**
+ * One thing the engine could not do for this query, parsed out of the
+ * envelope's `degraded[]`.
+ *
+ * The backend concatenates its own contribution with the backend's and the
+ * facet counter's WITHOUT de-duplicating (`services.py`), so the same literal
+ * can arrive twice; {@link SearchDegradation} values are de-duplicated by
+ * `raw` when parsed.
+ */
+export type SearchDegradationKind =
+  | "typo_tolerance"
+  | "phrase_synonyms"
+  | "exact_total"
+  | "exact_facet_counts"
+  | "category_rollup"
+  | "scorer"
+  | "unknown";
+
+export interface SearchDegradation {
+  readonly kind: SearchDegradationKind;
+  /** The literal the server sent — shown for an `unknown` kind, because a
+   * degradation this build has no sentence for is still a degradation. */
+  readonly raw: string;
+  /** For `kind: "scorer"`, the scorer slug after the `scorer:` prefix. */
+  readonly scorer?: string;
+  /** i18n key for the sentence. */
+  readonly messageKey: string;
+}

package/src/default/DegradationNotice.tsx

@@ -0,0 +1,50 @@
+/**
+ * `degraded[]`, on the screen.
+ *
+ * The whole point of the backend declaring its degradations per query is that
+ * a client can tell the person. A banner is not decoration here: "counts are
+ * approximate" and "subcategories may be missing" change what the page MEANS,
+ * and the spec calls swallowing them the same class of defect as `data ?? []`.
+ *
+ * An `unknown` degradation still renders — with the raw literal, because a
+ * build that predates a new limitation should say "the engine reported
+ * something we have no wording for: X", not nothing at all.
+ */
+import type { ReactElement } from "react";
+import { Alert, Typography } from "antd";
+import { useT } from "@stapel/core";
+import type { SearchDegradation } from "../api/types.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+export interface DegradationNoticeProps {
+  readonly degradations: readonly SearchDegradation[];
+}
+
+export function DegradationNotice(
+  props: DegradationNoticeProps
+): ReactElement | null {
+  const t = useT();
+  if (props.degradations.length === 0) return null;
+  return (
+    <Alert
+      type="warning"
+      showIcon
+      data-testid="search-degraded"
+      message={t(SEARCH_I18N_KEYS.degradedTitle)}
+      description={
+        <ul style={{ margin: 0, paddingInlineStart: 20 }}>
+          {props.degradations.map((degradation) => (
+            <li key={degradation.raw} data-degradation={degradation.raw}>
+              <Typography.Text type="secondary">
+                {t(degradation.messageKey, {
+                  scorer: degradation.scorer ?? "",
+                  raw: degradation.raw,
+                })}
+              </Typography.Text>
+            </li>
+          ))}
+        </ul>
+      }
+    />
+  );
+}

package/src/default/ErrorAlert.tsx

@@ -0,0 +1,46 @@
+/**
+ * The one error surface this pair's default skin renders, so the split copy
+ * core produces reaches a screen the same way everywhere (mirrors the
+ * docs/notifications/workspaces etalon).
+ *
+ * Core's `describeFlowError` splits a failure into the sentence a person
+ * reads and the technical detail a support agent quotes (owner report
+ * 2026-08-09: the status used to be spliced into the sentence, ending in a
+ * bare `" (500)"`). The split only helps if a skin renders both halves at
+ * their own weights: `message` at normal weight, `detail` muted and small.
+ *
+ * `undefined` in — including a `detail` core left `undefined` because there
+ * was nothing worth quoting — renders nothing rather than an empty line.
+ */
+import { Alert, Typography } from "antd";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import type { FlowErrorDisplay } from "@stapel/core";
+
+export function ErrorAlert(props: {
+  error: FlowErrorDisplay | undefined;
+  style?: CSSProperties | undefined;
+  testId?: string | undefined;
+  action?: ReactNode;
+}): ReactElement | null {
+  const { error } = props;
+  if (!error) return null;
+  return (
+    <Alert
+      type="error"
+      showIcon
+      {...(props.style ? { style: props.style } : {})}
+      {...(props.testId ? { "data-testid": props.testId } : {})}
+      {...(props.action ? { action: props.action } : {})}
+      message={error.message}
+      {...(error.detail
+        ? {
+            description: (
+              <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                {error.detail}
+              </Typography.Text>
+            ),
+          }
+        : {})}
+    />
+  );
+}

package/src/default/FacetPanelPane.tsx

@@ -0,0 +1,174 @@
+/**
+ * `<FacetPanelPane>` — the antd facet panel.
+ *
+ * Three things it is obliged to render, all of which a naive panel drops:
+ *
+ *  - the count NEXT TO EVERY OPTION, including the ones you have not chosen.
+ *    Facets are counted with their own filter removed, so those numbers are
+ *    "what you would get by switching to this instead" — a sibling that shows
+ *    a stale or zeroed count has converted a drill-down facet into a naive one.
+ *  - `approximate` — said in words, from the first day, because the counts
+ *    genuinely are a sample above the backend's candidate cap.
+ *  - `skipped` — the slugs the server did not count at all. Their options show
+ *    "not counted", never `0`. A silent zero there is the same defect class as
+ *    `data ?? []`: a number that looks like an answer and is not one.
+ */
+import type { ReactElement } from "react";
+import { Alert, Button, Checkbox, Empty, Flex, Spin, Tag, Typography } from "antd";
+import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { FacetPanel } from "../headless/FacetPanel.js";
+import type { FacetGroup, FacetOption } from "../state/facets.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { SearchSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface FacetPanelPaneProps extends ThemeModeProp {
+  /** The category's feature schema — the source of option LABELS. */
+  readonly categoryFeatures?: readonly FeatureDef[];
+  readonly locale?: string;
+  readonly enabled?: boolean;
+}
+
+function OptionRow(props: {
+  group: FacetGroup;
+  option: FacetOption;
+  onToggle: (slug: string, value: string) => void;
+}): ReactElement {
+  const t = useT();
+  const { option, group } = props;
+  return (
+    <Flex justify="space-between" align="center" gap={8}>
+      <Checkbox
+        checked={option.selected}
+        data-testid={`facet-option-${group.slug}-${option.value}`}
+        data-analytics="none"
+        data-analytics-reason="a filter is a read, not a flow step"
+        onChange={() => {
+          props.onToggle(group.slug, option.value);
+        }}
+      >
+        {option.label}
+      </Checkbox>
+      {option.count === null ? (
+        <Tag data-testid={`facet-count-${group.slug}-${option.value}`}>
+          {t(SEARCH_I18N_KEYS.facetsNotCounted)}
+        </Tag>
+      ) : (
+        <Typography.Text
+          type="secondary"
+          data-testid={`facet-count-${group.slug}-${option.value}`}
+        >
+          {option.count}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}
+
+export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+
+  return (
+    <SearchSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <FacetPanel
+        {...(props.categoryFeatures !== undefined
+          ? { categoryFeatures: props.categoryFeatures }
+          : {})}
+        {...(props.locale !== undefined ? { locale: props.locale } : {})}
+        {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}
+      >
+        {(bag) => (
+          <Flex vertical gap={12} data-testid="search-facets">
+            <Flex justify="space-between" align="center" gap={8}>
+              <Typography.Title level={5} style={{ margin: 0 }}>
+                {t(SEARCH_I18N_KEYS.facetsTitle)}
+              </Typography.Title>
+              {bag.activeFilters > 0 && (
+                <Button
+                  size="small"
+                  onClick={bag.clearAll}
+                  data-analytics="none"
+                  data-analytics-reason="a filter is a read, not a flow step"
+                  data-testid="facets-clear-all"
+                >
+                  {t(SEARCH_I18N_KEYS.facetsClearAll, { count: bag.activeFilters })}
+                </Button>
+              )}
+            </Flex>
+
+            {bag.approximate && (
+              <Alert
+                type="info"
+                showIcon
+                data-testid="facets-approximate"
+                message={t(SEARCH_I18N_KEYS.facetsApproximate)}
+              />
+            )}
+            {bag.skipped.length > 0 && (
+              <Alert
+                type="warning"
+                showIcon
+                data-testid="facets-skipped"
+                message={t(SEARCH_I18N_KEYS.facetsSkipped, {
+                  slugs: bag.skipped.join(", "),
+                })}
+              />
+            )}
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 16 }}>
+                  <Spin data-testid="facets-loading" />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="facets-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(SEARCH_I18N_KEYS.facetsLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="facets-empty"
+                  description={t(SEARCH_I18N_KEYS.facetsEmpty)}
+                />
+              ),
+              ready: (groups) => (
+                <Flex vertical gap={16}>
+                  {groups.map((group) => (
+                    <Flex
+                      vertical
+                      gap={4}
+                      key={group.slug}
+                      data-testid={`facet-group-${group.slug}`}
+                      data-counted={group.counted ? "true" : "false"}
+                    >
+                      <Typography.Text strong>{group.label}</Typography.Text>
+                      {group.options.map((option) => (
+                        <OptionRow
+                          key={option.value}
+                          group={group}
+                          option={option}
+                          onToggle={bag.toggle}
+                        />
+                      ))}
+                    </Flex>
+                  ))}
+                  <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                    {t(SEARCH_I18N_KEYS.facetsDrillDownHint)}
+                  </Typography.Text>
+                </Flex>
+              ),
+            })}
+          </Flex>
+        )}
+      </FacetPanel>
+    </SearchSkinTheme>
+  );
+}

package/src/default/RankingDisclosurePane.tsx

@@ -0,0 +1,116 @@
+/**
+ * `<RankingDisclosurePane>` — the P2B Art. 5 page: which parameters decide
+ * the order of results, their relative weight, and which of them the
+ * configured engine cannot actually evaluate.
+ *
+ * Generated from the backend's scorer registry, so it cannot drift from the
+ * ranking it describes — which is the only version of this page worth
+ * shipping.
+ */
+import type { ReactElement } from "react";
+import { Empty, Flex, List, Spin, Tag, Typography } from "antd";
+import { matchList, toFlowError, useDescribeFlowError, useT } from "@stapel/core";
+import type { Scorer } from "../api/types.js";
+import { RankingDisclosure } from "../headless/RankingDisclosure.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { SearchSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface RankingDisclosurePaneProps extends ThemeModeProp {
+  /** Doc type to disclose; omitted asks for the deployment's default. */
+  readonly type?: string;
+}
+
+export function RankingDisclosurePane(
+  props: RankingDisclosurePaneProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+
+  return (
+    <SearchSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <RankingDisclosure {...(props.type !== undefined ? { type: props.type } : {})}>
+        {(bag) => (
+          <Flex vertical gap={12} data-testid="search-ranking">
+            <Typography.Title level={4} style={{ margin: 0 }}>
+              {t(SEARCH_I18N_KEYS.rankingTitle)}
+            </Typography.Title>
+            <Typography.Paragraph type="secondary" style={{ margin: 0 }}>
+              {t(SEARCH_I18N_KEYS.rankingIntro)}
+            </Typography.Paragraph>
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 16 }}>
+                  <Spin data-testid="ranking-loading" />
+                </Flex>
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="ranking-failed"
+                  error={{
+                    ...describe(toFlowError(error)),
+                    message: t(SEARCH_I18N_KEYS.rankingLoadFailed),
+                  }}
+                />
+              ),
+              empty: () => (
+                <Empty
+                  data-testid="ranking-empty"
+                  description={t(SEARCH_I18N_KEYS.rankingEmpty)}
+                />
+              ),
+              ready: (scorers) => (
+                <List<Scorer>
+                  data-testid="ranking-list"
+                  dataSource={[...scorers]}
+                  renderItem={(scorer) => (
+                    <List.Item key={scorer.slug} data-scorer={scorer.slug}>
+                      <Flex vertical gap={2} style={{ width: "100%" }}>
+                        <Flex justify="space-between" align="center" gap={8}>
+                          <Typography.Text strong>
+                            {t(scorer.description_key)}
+                          </Typography.Text>
+                          <Tag>{scorer.weight}</Tag>
+                        </Flex>
+                        <Typography.Text type="secondary">
+                          {scorer.description}
+                        </Typography.Text>
+                        <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                          {t(SEARCH_I18N_KEYS.rankingAppliesTo)}
+                          {": "}
+                          {scorer.applies_to_sorts.join(", ")}
+                        </Typography.Text>
+                        {!scorer.active && (
+                          <Typography.Text type="warning" data-testid="ranking-inactive">
+                            {t(SEARCH_I18N_KEYS.rankingInactive, {
+                              reason: scorer.inactive_reason,
+                            })}
+                          </Typography.Text>
+                        )}
+                      </Flex>
+                    </List.Item>
+                  )}
+                />
+              ),
+            })}
+
+            {bag.notes.length > 0 && (
+              <Flex vertical gap={2}>
+                <Typography.Text strong>
+                  {t(SEARCH_I18N_KEYS.rankingNotes)}
+                </Typography.Text>
+                {bag.notes.map((note) => (
+                  <Typography.Text type="secondary" key={note}>
+                    {note}
+                  </Typography.Text>
+                ))}
+              </Flex>
+            )}
+          </Flex>
+        )}
+      </RankingDisclosure>
+    </SearchSkinTheme>
+  );
+}

package/src/default/SearchPage.tsx

@@ -0,0 +1,87 @@
+/**
+ * `<SearchPage>` — the composed screen the nav manifest points at: filters on
+ * the left, sort and results on the right, the ranking link in the footer.
+ *
+ * It composes the two panes and owns NO state of its own. The URL is the
+ * state, and it arrives through the `adapter` prop — which is where a host
+ * hands in `useRouterSearchParams()` from `@stapel/search-react/router`, or
+ * its own binding. The page does not reach for a router, so the same
+ * component renders under react-router, under a Next.js app router, and in a
+ * test with a plain `URLSearchParams`.
+ *
+ * The three seams a storefront fills (spec §6.2 items 1–3): `renderCard`
+ * (a `<ListingCard>`), `categoryFeatures` (from categories-react, for facet
+ * labels), and `footer` (the container's own chrome). None of them is
+ * optional behaviour in disguise — every one has a working default.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Col, Flex, Row, Typography } from "antd";
+import { useT } from "@stapel/core";
+import type { FeatureDef } from "@stapel/attributes-react";
+import { SearchStateProvider } from "../headless/SearchStateProvider.js";
+import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
+import type { ParseSearchStateOptions } from "../state/urlState.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { FacetPanelPane } from "./FacetPanelPane.js";
+import { SearchResultsPane } from "./SearchResultsPane.js";
+import { SortSelect } from "./SortSelect.js";
+import type { SearchCardRenderer } from "./SearchResultCard.js";
+import { SearchSkinTheme } from "./theme.js";
+import { UrlIssueNotice } from "./UrlIssueNotice.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions {
+  /** The URL binding. `useRouterSearchParams()` from `./router` is the
+   * react-router one. */
+  readonly adapter: SearchParamsAdapter;
+  readonly renderCard?: SearchCardRenderer;
+  readonly categoryFeatures?: readonly FeatureDef[];
+  readonly locale?: string;
+  /** Container chrome under the results — e.g. the ranking-disclosure link. */
+  readonly footer?: ReactNode;
+}
+
+export function SearchPage(props: SearchPageProps): ReactElement {
+  const t = useT();
+  const {
+    adapter,
+    renderCard,
+    categoryFeatures,
+    locale,
+    footer,
+    mode,
+    ...parseOptions
+  } = props;
+
+  return (
+    <SearchSkinTheme {...(mode !== undefined ? { mode } : {})}>
+      <SearchStateProvider adapter={adapter} {...parseOptions}>
+        <Flex vertical gap={16} data-testid="search-page">
+          <UrlIssueNotice />
+          <Row gutter={[16, 16]}>
+            <Col xs={24} md={7}>
+              <FacetPanelPane
+                {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+                {...(locale !== undefined ? { locale } : {})}
+              />
+            </Col>
+            <Col xs={24} md={17}>
+              <Flex vertical gap={12}>
+                <Flex justify="space-between" align="center" wrap gap={8}>
+                  <Typography.Text type="secondary">
+                    {t(SEARCH_I18N_KEYS.resultsTitle)}
+                  </Typography.Text>
+                  <SortSelect />
+                </Flex>
+                <SearchResultsPane
+                  {...(renderCard !== undefined ? { renderCard } : {})}
+                  {...(footer !== undefined ? { footer } : {})}
+                />
+              </Flex>
+            </Col>
+          </Row>
+        </Flex>
+      </SearchStateProvider>
+    </SearchSkinTheme>
+  );
+}