@stapel/search-react 0.1.0

package/src/default/SearchResultCard.tsx

@@ -0,0 +1,96 @@
+/**
+ * The GENERIC card — the fallback behind `renderCard`, and the default the
+ * spec (§3.7) says the pair must ship.
+ *
+ * `SearchItem.card` is a free-form object: "stored row fields, so a result
+ * page costs one query". Which fields it holds is the DOC TYPE's business,
+ * not search's, so this card reads a small, documented set of conventional
+ * names and shows what it finds. A storefront replaces the whole thing by
+ * passing `renderCard` and rendering `<ListingCard>` from
+ * `@stapel/listings-react/default` — that is the slot seam, and the reason
+ * these two L2 pairs never import each other.
+ *
+ * The ONE thing a replacement card may not drop is the `promoted` marking:
+ * DSA Art. 26 makes it mandatory, the serializer puts it on every item under
+ * every sort, and a storefront where some lists show it and some do not is
+ * legally worse than one that never showed it. `renderCard` receives the whole
+ * item so the marking is always reachable, and this default renders it.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Card, Flex, Tag, Tooltip, Typography } from "antd";
+import { useT } from "@stapel/core";
+import type { SearchItem } from "../api/types.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+/** What the card slot is handed. */
+export interface SearchCardProps {
+  readonly item: SearchItem;
+}
+
+/** A card renderer a host supplies for `renderCard`. */
+export type SearchCardRenderer = (item: SearchItem) => ReactNode;
+
+function text(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+/**
+ * The conventional field names this default reads off `card`. Documented
+ * rather than guessed at each site, and deliberately short: anything richer
+ * belongs in the owning pair's own card.
+ */
+export const GENERIC_CARD_FIELDS: readonly string[] = [
+  "title",
+  "price",
+  "currency",
+  "location",
+  "image_url",
+];
+
+export function SearchResultCard(props: SearchCardProps): ReactElement {
+  const t = useT();
+  const card = props.item.card;
+  const title = text(card["title"]) ?? t(SEARCH_I18N_KEYS.resultsUntitled);
+  const price = text(card["price"]);
+  const currency = text(card["currency"]);
+  const location = text(card["location"]);
+  const distance =
+    props.item.distance_km !== null
+      ? t(SEARCH_I18N_KEYS.resultsDistanceKm, {
+          km: props.item.distance_km.toFixed(1),
+        })
+      : undefined;
+
+  return (
+    <Card
+      size="small"
+      data-testid="search-result-card"
+      data-promoted={props.item.promoted ? "true" : "false"}
+    >
+      <Flex vertical gap={4}>
+        <Flex justify="space-between" align="start" gap={8}>
+          <Typography.Text strong>{title}</Typography.Text>
+          {props.item.promoted && (
+            <Tooltip title={t(SEARCH_I18N_KEYS.resultsPromotedHint)}>
+              <Tag color="gold" data-testid="search-result-promoted">
+                {t(SEARCH_I18N_KEYS.resultsPromoted)}
+              </Tag>
+            </Tooltip>
+          )}
+        </Flex>
+        {price !== undefined && (
+          <Typography.Text>
+            {currency !== undefined ? `${price} ${currency}` : price}
+          </Typography.Text>
+        )}
+        {(location !== undefined || distance !== undefined) && (
+          <Typography.Text type="secondary">
+            {[location, distance].filter((v) => v !== undefined).join(" · ")}
+          </Typography.Text>
+        )}
+      </Flex>
+    </Card>
+  );
+}

package/src/default/SearchResultsPane.tsx

@@ -0,0 +1,173 @@
+/**
+ * `<SearchResultsPane>` — the antd result page: the count, the degradation
+ * banner, the cards, and the keyset controls.
+ *
+ * Rendered through core's `matchList`, whose FOUR required arms are the point.
+ * "Nothing matches this search" is reachable only from a search that actually
+ * ran; a 5xx renders "we could not run this search" plus a retry. The
+ * substitution of one for the other is what cost the 2026-08-09 incident, and
+ * the spec's §7.4 negative leg exercises this exact pane against a forced 5xx.
+ *
+ * The window refusal gets its own sentence. `error.400.search_window_exceeded`
+ * is "narrow the search", not "there is nothing here" — it arrives as a 400
+ * with an empty body, which is precisely how it would otherwise render as an
+ * empty page.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Empty, Flex, Spin, Typography } from "antd";
+import {
+  errorCode,
+  matchList,
+  toFlowError,
+  useDescribeFlowError,
+  useT,
+} from "@stapel/core";
+import type { SearchItem } from "../api/types.js";
+import { SearchResults } from "../headless/SearchResults.js";
+import type { SearchResultsBag } from "../headless/SearchResults.js";
+import { SEARCH_WINDOW_EXCEEDED } from "../i18n/errorsMap.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { DegradationNotice } from "./DegradationNotice.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { SearchResultCard } from "./SearchResultCard.js";
+import type { SearchCardRenderer } from "./SearchResultCard.js";
+import { SearchSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface SearchResultsPaneProps extends ThemeModeProp {
+  /**
+   * The card slot (spec §6.2 item 1). A storefront passes
+   * `(item) => <ListingCard …/>`; omitted, the generic card renders.
+   * Either way the `promoted` marking is the renderer's obligation and the
+   * default honours it.
+   */
+  readonly renderCard?: SearchCardRenderer;
+  /** Rendered under the pager — where the container puts the ranking link. */
+  readonly footer?: ReactNode;
+  readonly enabled?: boolean;
+}
+
+function Count(props: { bag: SearchResultsBag }): ReactElement | null {
+  const t = useT();
+  const page = props.bag.page;
+  if (page === null) return null;
+  return (
+    <Typography.Text type="secondary" data-testid="search-count">
+      {page.countIsEstimate
+        ? t(SEARCH_I18N_KEYS.resultsCountApproximate, { count: page.count })
+        : t(SEARCH_I18N_KEYS.resultsCountExact, { count: page.count })}
+    </Typography.Text>
+  );
+}
+
+function Pager(props: { bag: SearchResultsBag }): ReactElement {
+  const t = useT();
+  const { prev, next, goPrev, goNext } = props.bag;
+  return (
+    <Flex gap={8} justify="center" data-testid="search-pager">
+      <Button
+        disabled={!prev.available}
+        title={prev.available ? undefined : t(prev.block.code, prev.block.params)}
+        onClick={goPrev}
+        data-analytics="none"
+        data-analytics-reason="keyset paging is a read, not a flow step"
+        data-testid="search-prev"
+      >
+        {t(SEARCH_I18N_KEYS.resultsPrev)}
+      </Button>
+      <Button
+        disabled={!next.available}
+        title={next.available ? undefined : t(next.block.code, next.block.params)}
+        onClick={goNext}
+        data-analytics="none"
+        data-analytics-reason="keyset paging is a read, not a flow step"
+        data-testid="search-next"
+      >
+        {t(SEARCH_I18N_KEYS.resultsNext)}
+      </Button>
+    </Flex>
+  );
+}
+
+export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const renderCard = props.renderCard;
+
+  return (
+    <SearchSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
+        {(bag) => (
+          <Flex vertical gap={16}>
+            <Flex justify="space-between" align="center" wrap gap={8}>
+              <Typography.Title level={4} style={{ margin: 0 }}>
+                {t(SEARCH_I18N_KEYS.resultsTitle)}
+              </Typography.Title>
+              <Count bag={bag} />
+            </Flex>
+
+            <DegradationNotice degradations={bag.degradations} />
+
+            {matchList(bag.state, {
+              loading: () => (
+                <Flex justify="center" style={{ padding: 24 }}>
+                  <Spin data-testid="search-loading" />
+                </Flex>
+              ),
+              failed: (error) => {
+                // The window refusal is a DIFFERENT sentence from a failed
+                // search, and both are different from "nothing found".
+                const isWindow = errorCode(error) === SEARCH_WINDOW_EXCEEDED;
+                return (
+                  <ErrorAlert
+                    testId={isWindow ? "search-window-exceeded" : "search-failed"}
+                    error={{
+                      ...describe(toFlowError(error)),
+                      message: t(
+                        isWindow
+                          ? SEARCH_I18N_KEYS.resultsWindowExceeded
+                          : SEARCH_I18N_KEYS.resultsLoadFailed
+                      ),
+                    }}
+                    action={
+                      <Button
+                        size="small"
+                        onClick={bag.refetch}
+                        data-analytics="none"
+                        data-analytics-reason="retry of a failed read; no flow to step"
+                      >
+                        {t(SEARCH_I18N_KEYS.resultsRetry)}
+                      </Button>
+                    }
+                  />
+                );
+              },
+              empty: () => (
+                <Empty
+                  data-testid="search-empty"
+                  description={t(SEARCH_I18N_KEYS.resultsEmpty)}
+                />
+              ),
+              ready: (items) => (
+                <Flex vertical gap={12} data-testid="search-results">
+                  {items.map((item: SearchItem) => (
+                    <div key={item.key}>
+                      {renderCard !== undefined ? (
+                        renderCard(item)
+                      ) : (
+                        <SearchResultCard item={item} />
+                      )}
+                    </div>
+                  ))}
+                </Flex>
+              ),
+            })}
+
+            <Pager bag={bag} />
+            {props.footer}
+          </Flex>
+        )}
+      </SearchResults>
+    </SearchSkinTheme>
+  );
+}

package/src/default/SortSelect.tsx

@@ -0,0 +1,77 @@
+/**
+ * The sort control.
+ *
+ * The options are the shipped `SORTS` list, NOT an enum from the schema —
+ * `docs/schema.json` declares none, and a deployment may register more. So a
+ * value the URL already carries that is not in the list is still offered as a
+ * (raw) option rather than silently reset: resetting it would rewrite a
+ * shared link's meaning on load, and the server is the one entitled to refuse
+ * an unknown sort (`error.400.search_unknown_sort`, which names it).
+ *
+ * `sort=distance` needs a centre — the server answers
+ * `error.400.search_sort_needs_center` without one. The option is therefore
+ * DISABLED with the reason named when no geo centre is set, rather than
+ * offered and then refused.
+ */
+import type { ReactElement } from "react";
+import { Flex, Select, Typography } from "antd";
+import { useT } from "@stapel/core";
+import { SEARCH_SORTS } from "../api/types.js";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+const SORT_LABEL_KEY: Readonly<Record<string, string>> = {
+  relevance: SEARCH_I18N_KEYS.sortRelevance,
+  newest: SEARCH_I18N_KEYS.sortNewest,
+  price_asc: SEARCH_I18N_KEYS.sortPriceAsc,
+  price_desc: SEARCH_I18N_KEYS.sortPriceDesc,
+  distance: SEARCH_I18N_KEYS.sortDistance,
+};
+
+export interface SortSelectProps {
+  /** The sort the SERVER applied, shown when the URL names none. */
+  readonly appliedSort?: string | undefined;
+}
+
+export function SortSelect(props: SortSelectProps): ReactElement {
+  const t = useT();
+  const { state, setSort } = useSearchState();
+
+  const hasCentre = state.geo !== undefined;
+  const known = new Set(SEARCH_SORTS);
+  const values =
+    state.sort !== undefined && !known.has(state.sort)
+      ? [...SEARCH_SORTS, state.sort]
+      : SEARCH_SORTS;
+
+  return (
+    <Flex gap={8} align="center">
+      <Typography.Text type="secondary">
+        {t(SEARCH_I18N_KEYS.sortLabel)}
+      </Typography.Text>
+      <Select<string>
+        data-testid="search-sort"
+        style={{ minWidth: 180 }}
+        value={state.sort ?? props.appliedSort ?? null}
+        placeholder={t(SEARCH_I18N_KEYS.sortLabel)}
+        onChange={(next) => {
+          setSort(next);
+        }}
+        options={values.map((value) => {
+          const key = SORT_LABEL_KEY[value];
+          const needsCentre = value === "distance" && !hasCentre;
+          return {
+            value,
+            label: key !== undefined ? t(key) : value,
+            disabled: needsCentre,
+            // A disabled control states its reason (the ActionAvailability
+            // canon), even inside a select.
+            ...(needsCentre
+              ? { title: t("error.400.search_sort_needs_center") }
+              : {}),
+          };
+        })}
+      />
+    </Flex>
+  );
+}

package/src/default/UrlIssueNotice.tsx

@@ -0,0 +1,37 @@
+/**
+ * "Part of this link could not be read."
+ *
+ * A shared search is a link somebody typed, edited, or truncated in a chat
+ * app. When the codec cannot read a parameter it reports the fact rather than
+ * dropping it silently — because the silent version WIDENS the search (a
+ * broken `lat` removes the location filter) and the person is then looking at
+ * something other than what was shared, with nothing on screen to say so.
+ */
+import type { ReactElement } from "react";
+import { Alert } from "antd";
+import { useT } from "@stapel/core";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+export function UrlIssueNotice(): ReactElement | null {
+  const t = useT();
+  const { issues } = useSearchState();
+  if (issues.length === 0) return null;
+  return (
+    <Alert
+      type="warning"
+      showIcon
+      data-testid="search-url-issues"
+      message={t(SEARCH_I18N_KEYS.urlIssuesTitle)}
+      description={
+        <ul style={{ margin: 0, paddingInlineStart: 20 }}>
+          {issues.map((issue) => (
+            <li key={`${issue.param}:${issue.code}`}>
+              {t(issue.messageKey, { param: issue.param })}
+            </li>
+          ))}
+        </ul>
+      }
+    />
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,48 @@
+/**
+ * `@stapel/search-react/default` — the antd default skin.
+ *
+ * A SEPARATE entry point on purpose: the main entry is headless and carries
+ * no antd, so a storefront that renders its own cards over `<SearchResults>`
+ * never pays for this bundle (enforced by size-limit and the bundle-purity
+ * test).
+ *
+ * Three override levers, none of which requires forking anything:
+ *
+ *  1. **`renderCard`** — the card slot. A storefront passes
+ *     `<ListingCard>` from `@stapel/listings-react/default`; the generic card
+ *     here is the documented default, not the intended end state (spec §3.7).
+ *  2. **`categoryFeatures`** — the facet-label slot. The server sends
+ *     `{value: count}` and no labels; the schema that names them lives in
+ *     categories, and the container hands it in (spec §6.2 item 2).
+ *  3. **retheming through the §68 token JSON** — every surface wraps itself
+ *     in `<SearchSkinTheme>`, so a host's regenerated `--stapel-*` custom
+ *     properties reach this skin with zero code.
+ */
+
+// ── surfaces ────────────────────────────────────────────────────────────────
+export { SearchPage } from "./SearchPage.js";
+export type { SearchPageProps } from "./SearchPage.js";
+
+export { SearchResultsPane } from "./SearchResultsPane.js";
+export type { SearchResultsPaneProps } from "./SearchResultsPane.js";
+
+export { FacetPanelPane } from "./FacetPanelPane.js";
+export type { FacetPanelPaneProps } from "./FacetPanelPane.js";
+
+export { RankingDisclosurePane } from "./RankingDisclosurePane.js";
+export type { RankingDisclosurePaneProps } from "./RankingDisclosurePane.js";
+
+// ── parts, exported so a host can compose or wrap one ───────────────────────
+export { SearchResultCard, GENERIC_CARD_FIELDS } from "./SearchResultCard.js";
+export type { SearchCardProps, SearchCardRenderer } from "./SearchResultCard.js";
+export { DegradationNotice } from "./DegradationNotice.js";
+export type { DegradationNoticeProps } from "./DegradationNotice.js";
+export { UrlIssueNotice } from "./UrlIssueNotice.js";
+export { SortSelect } from "./SortSelect.js";
+export type { SortSelectProps } from "./SortSelect.js";
+export { ErrorAlert } from "./ErrorAlert.js";
+
+// ── theming ─────────────────────────────────────────────────────────────────
+export { SearchSkinTheme } from "./theme.js";
+export type { SearchSkinThemeProps } from "./theme.js";
+export type { ThemeModeProp } from "./types.js";

package/src/default/theme.tsx

@@ -0,0 +1,66 @@
+/**
+ * The default skin's INTERNAL theme provider — every `/default` surface wraps
+ * itself in this, so the skin is readable no matter what the host supplies
+ * (tracker #26: a skin set with no internal provider once inherited a theme
+ * bridge serving light-mode values inside a dark document — text on
+ * background at 1.00:1). The theme derives from `@stapel/tokens` via
+ * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
+ * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
+ * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
+ *
+ * This is also what "override styles" means for this pair: a storefront
+ * retheming through the §68 token JSON regenerates its `--stapel-*` custom
+ * properties and the result page follows with zero code — a far better deal
+ * than a prop-per-colour API, and the reason the skin has none.
+ */
+import { useMemo } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { ConfigProvider } from "antd";
+import {
+  resolveThemeMode,
+  toAntdTheme,
+  toAntdThemeConfig,
+} from "@stapel/tokens-antd";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+export interface SearchSkinThemeProps {
+  /**
+   * Light or dark. Defaults to the mode the host's document declares
+   * (`resolveThemeMode()`). Pass explicitly to pin a side.
+   */
+  readonly mode?: ThemeMode;
+  /** Extra styles merged onto the themed root element (layout only — colors
+   * come from the mode). */
+  readonly style?: CSSProperties;
+  readonly children: ReactNode;
+}
+
+/**
+ * `<SearchSkinTheme/>` — the self-theming wrapper of
+ * `@stapel/search-react/default`. Standalone use is supported (wrap any
+ * composition of the skin's parts once); the shipped surfaces
+ * (`SearchPage`, `SearchResultsPane`, `FacetPanelPane`,
+ * `RankingDisclosurePane`) each already wrap themselves, and nested antd
+ * `ConfigProvider`s merge, so composing them under one `SearchSkinTheme`
+ * stays correct.
+ */
+export function SearchSkinTheme(props: SearchSkinThemeProps): ReactElement {
+  const mode = props.mode ?? resolveThemeMode();
+  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
+  const token = useMemo(() => toAntdTheme(mode), [mode]);
+  return (
+    <ConfigProvider theme={theme}>
+      <div
+        data-search-skin-root
+        data-search-skin-mode={mode}
+        style={{
+          color: token.colorText,
+          backgroundColor: token.colorBgContainer,
+          ...props.style,
+        }}
+      >
+        {props.children}
+      </div>
+    </ConfigProvider>
+  );
+}

package/src/default/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Small shared types for the `/default` skin — kept in one place so every
+ * surface takes the same `mode` prop and re-exports the same error dialect.
+ */
+export type { FlowError } from "@stapel/core";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+/** Every `/default` surface accepts a theme mode; absent means "whatever the
+ * host document declares" (`resolveThemeMode()`), never a hardcoded side. */
+export interface ThemeModeProp {
+  readonly mode?: ThemeMode;
+}

package/src/headless/FacetPanel.tsx

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad, useT } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { FeatureDef } from "@stapel/attributes-react";
+import type { FacetMeta, SearchRange } from "../api/types.js";
+import { useSearchQuery } from "../model/queries.js";
+import { buildFacetGroups } from "../state/facets.js";
+import type { FacetGroup } from "../state/facets.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+/** The bag `<FacetPanel>` hands its render prop. */
+export interface FacetPanelBag {
+  /**
+   * The facet groups as a state a skin cannot flatten. `empty` means the
+   * search genuinely has no facets to offer (facets off, or no plan for the
+   * category) — it is NOT what a failed query looks like.
+   */
+  readonly state: LoadState<readonly FacetGroup[]>;
+  /**
+   * `true` when the counts came from a SAMPLE because the candidate set
+   * exceeded the backend's cap. The panel must say so — the spec makes this
+   * a first-day requirement, not a banner added after somebody notices the
+   * numbers moving (§12 risk 3).
+   */
+  readonly approximate: boolean;
+  /**
+   * Plan slugs the server dropped at `MAX_FACET_FIELDS`. Reported, not
+   * vanished — the backend's own words. A skin names them; it never renders
+   * a zero in their place.
+   */
+  readonly skipped: readonly string[];
+  /** Slugs that WERE counted. */
+  readonly counted: readonly string[];
+  /** Size of the largest counted set — the number `approximate` is about. */
+  readonly candidates: number;
+  /** Facet values + ranges + geo currently applied. */
+  readonly activeFilters: number;
+
+  toggle(slug: string, value: string): void;
+  setRange(slug: string, range: SearchRange | null): void;
+  clear(slug: string): void;
+  clearAll(): void;
+}
+
+const EMPTY_META: FacetMeta = {
+  approximate: false,
+  candidates: 0,
+  counted: [],
+  skipped: [],
+};
+
+/**
+ * Headless facet panel over the CURRENT search.
+ *
+ * It runs the same query as `<SearchResults>` — same state, same key, so
+ * TanStack serves both from one request. That is deliberate: facets and rows
+ * come from one envelope server-side (one query per page is the contract's
+ * stated design), and fetching them separately would put two answers about
+ * one search on the screen at once.
+ *
+ * `categoryFeatures` is the second slot-seam of the pair (spec §6.2 item 2).
+ * The server sends `{value: count}` and no labels, because the labels are
+ * translation keys in the category's own schema. Hand them in and the options
+ * read as words; leave them out and they read as raw index terms — never as
+ * blanks.
+ */
+export function FacetPanel(props: {
+  /** From `categories-react`'s `GET /categories/{id}/features/`. */
+  categoryFeatures?: readonly FeatureDef[];
+  /** BCP-47 tag for `date`-typed option labels. Defaults to the runtime's. */
+  locale?: string;
+  enabled?: boolean;
+  children: (bag: FacetPanelBag) => ReactNode;
+}): ReactNode {
+  const { state: searchState, setFilter, setRange, clearAll, toggleFilter, activeFilters } =
+    useSearchState();
+  const t = useT();
+  const query = useSearchQuery(
+    searchState,
+    props.enabled !== undefined ? { enabled: props.enabled } : undefined
+  );
+
+  const envelope = loadStateFromQuery(query);
+  const meta = envelope.status === "ready" ? envelope.data.facet_meta : EMPTY_META;
+
+  const groups = mapLoad(envelope, (data) =>
+    buildFacetGroups({
+      facets: data.facets,
+      meta: data.facet_meta,
+      state: searchState,
+      ...(props.categoryFeatures !== undefined
+        ? { categoryFeatures: props.categoryFeatures }
+        : {}),
+      t,
+      ...(props.locale !== undefined ? { locale: props.locale } : {}),
+    })
+  );
+
+  return props.children({
+    state: groups,
+    approximate: meta.approximate,
+    skipped: meta.skipped,
+    counted: meta.counted,
+    candidates: meta.candidates,
+    activeFilters,
+    toggle: toggleFilter,
+    setRange,
+    clear: (slug) => {
+      setFilter(slug, []);
+    },
+    clearAll,
+  });
+}

package/src/headless/RankingDisclosure.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { RankingResponse, Scorer } from "../api/types.js";
+import { useRankingDisclosure } from "../model/queries.js";
+
+/** The bag `<RankingDisclosure>` hands its render prop. */
+export interface RankingDisclosureBag {
+  /**
+   * The ranking parameters. `empty` means the deployment declares none — a
+   * legitimate answer for a naive backend, and a different sentence from
+   * "we could not fetch the disclosure".
+   */
+  readonly state: LoadState<readonly Scorer[]>;
+  readonly disclosure: LoadState<RankingResponse>;
+  /**
+   * Parameters the CONFIGURED engine cannot evaluate (`active: false`). They
+   * are listed with their `inactive_reason`, not filtered out: a disclosure
+   * that quietly dropped them would be disclosing a ranking the site does not
+   * actually use — which is the failure mode P2B Art. 5 exists to prevent.
+   */
+  readonly inactive: readonly Scorer[];
+  readonly docType: string | null;
+  readonly backend: string | null;
+  readonly notes: readonly string[];
+  refetch(): void;
+}
+
+/**
+ * Headless P2B Art. 5 ranking disclosure — "what determines the order of
+ * these results", straight from the backend's scorer registry rather than
+ * from prose somebody has to remember to update.
+ *
+ * Pair this with the DSA Art. 26 half: `SearchItem.promoted` marks the paid
+ * placements in the list itself, and this explains the ordering of everything
+ * else. Neither substitutes for the other.
+ */
+export function RankingDisclosure(props: {
+  /** Doc type to disclose. Omitted asks for the deployment's default. */
+  type?: string;
+  children: (bag: RankingDisclosureBag) => ReactNode;
+}): ReactNode {
+  const query = useRankingDisclosure(props.type);
+  const disclosure = loadStateFromQuery(query);
+  const data = disclosure.status === "ready" ? disclosure.data : null;
+
+  return props.children({
+    state: mapLoad(disclosure, (d) => d.scorers as readonly Scorer[]),
+    disclosure,
+    inactive: data === null ? [] : data.scorers.filter((s) => !s.active),
+    docType: data?.doc_type ?? null,
+    backend: data?.backend ?? null,
+    notes: data === null ? [] : data.notes,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}