@stapel/search-react 0.3.1 → 0.7.0

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "backend": {
     "module": "stapel-search",
-    "contract": ">=0.1 <0.2"
+    "contract": ">=0.2 <0.3"
   },
   "layers": [
     "api",
@@ -70,6 +70,17 @@
         "query",
         "{params}"
       ]
+    },
+    "useSuggest": {
+      "kind": "query",
+      "operation": "suggest",
+      "queryKey": [
+        "search",
+        "suggest",
+        "{type}",
+        "{q}",
+        "{…}"
+      ]
     }
   },
   "errors": {
@@ -393,47 +404,207 @@
   },
   "demos": [
     {
-      "id": "search.facets",
-      "title": "Facet panel",
-      "description": "Counts are computed with each facet's own filter removed, so picking one value does not zero its siblings. Labels come from the category schema through @stapel/attributes-react; a slug the server skipped shows 'not counted', never 0.",
-      "component": "FacetPanel",
+      "id": "search.box",
+      "title": "Search box",
+      "description": "Types into a draft and searches after a pause, so the address bar does not chase the keyboard; the URL still wins whenever it moves on its own, so the box can never show a word the results are not about. Capped at the server's own MAX_QUERY_CHARS, which makes 'query too long' a refusal this control cannot cause.",
+      "component": "SearchBox",
       "tokens": [
         "surface-raised"
       ],
       "variants": [
-        "default"
+        "empty",
+        "typed"
       ],
-      "source": "demo/FacetPanel.demo.tsx"
+      "source": "demo/SearchBox.demo.tsx"
     },
     {
-      "id": "search.ranking",
-      "title": "Ranking disclosure",
-      "description": "Which parameters order the results and how much each weighs, straight from the scorer registry. Parameters the configured engine cannot evaluate are listed with their reason rather than filtered out.",
-      "component": "RankingDisclosure",
+      "id": "search.degradation-notice",
+      "title": "Degradation notice",
+      "description": "What the engine could not do for THIS query, in words: the typo pass it skipped, the facet counts it sampled rather than counted, the scorer it could not evaluate. An unknown degradation still renders — with its raw literal — because a build that predates a limitation should say 'the engine reported something we have no wording for', not nothing.",
+      "component": "DegradationNotice",
       "tokens": [
         "surface-raised"
       ],
       "variants": [
-        "default"
+        "banner",
+        "inline"
       ],
-      "source": "demo/RankingDisclosure.demo.tsx"
+      "source": "demo/DegradationNotice.demo.tsx"
     },
     {
-      "id": "search.results",
-      "title": "Search results",
-      "description": "One keyset page, rendered through matchList so 'nothing found' can only be said about a search that actually ran. The count is marked as an estimate when the envelope says so, and degraded[] is surfaced rather than swallowed.",
-      "component": "SearchResults",
+      "id": "search.facet-panel-pane",
+      "title": "Filter panel",
+      "description": "The drill-down facet panel with every count beside its option — including the options you have not chosen, which is what makes them drill-down rather than naive — plus the server's honesty flags said in words: 'these counts are approximate' and the slugs it did not count at all, whose options read 'not counted' and never a zero that looks like an answer.",
+      "component": "FacetPanelPane",
       "covers": [
+        "FacetPanel"
+      ],
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "open-search",
+        "narrowed"
+      ],
+      "source": "demo/FacetPanelPane.demo.tsx"
+    },
+    {
+      "id": "search.filter-sheet",
+      "title": "Filter sheet",
+      "description": "The filters as a phone actually meets them: a bottom sheet over the results, with the drill-down counts beside every option, a Clear all for the two constraints the link arrived with, and a footer that commits by saying how many results the current choices lead to rather than a bare 'Apply'.",
+      "component": "SearchPage",
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "open"
+      ],
+      "source": "demo/FilterSheet.demo.tsx"
+    },
+    {
+      "id": "search.language-select",
+      "title": "Language filter",
+      "description": "The languages a deployment indexes, each named the way THIS reader would name it. With nothing offered and nothing applied the control does not render at all: a select whose only option is 'any' is a dead control, and the panel is thinner without it.",
+      "component": "LanguageSelect",
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "offered",
+        "from-a-link"
+      ],
+      "source": "demo/LanguageSelect.demo.tsx"
+    },
+    {
+      "id": "search.page",
+      "title": "Search page",
+      "description": "The composed /s screen: the query box bound to setText, the filter panel (category and location slots, numeric ranges, drill-down facets), the sort and page-size toolbar, and one keyset page of cards with the DSA promoted marking explained in words rather than in a tooltip.",
+      "component": "SearchPage",
+      "covers": [
+        "SearchStateProvider",
         "SearchProvider",
-        "SearchStateProvider"
+        "SearchResults",
+        "FacetPanel"
+      ],
+      "tokens": [
+        "surface-raised",
+        "warning-bg"
+      ],
+      "variants": [
+        "desktop",
+        "phone",
+        "unreadable-link"
+      ],
+      "source": "demo/SearchPage.demo.tsx"
+    },
+    {
+      "id": "search.page-size-select",
+      "title": "Page size control",
+      "description": "A short ladder around the server's DEFAULT_PAGE_SIZE. Choosing a size REPLACES the history entry rather than pushing one: a page size is a preference, not a step through the results, and Back should still undo the last filter.",
+      "component": "PageSizeSelect",
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "ladder",
+        "off-ladder"
       ],
+      "source": "demo/PageSizeSelect.demo.tsx"
+    },
+    {
+      "id": "search.range-filter-row",
+      "title": "Numeric range filter",
+      "description": "A range row per numeric feature of the category schema, plus any slug the URL already constrains — because a constraint that is active must always have a control that removes it, even when the schema no longer explains it. Bounds and step come from the schema; the unit is shown in the field's accessible name.",
+      "component": "RangeFilterRow",
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "untouched",
+        "applied"
+      ],
+      "source": "demo/RangeFilterRow.demo.tsx"
+    },
+    {
+      "id": "search.ranking-pane",
+      "title": "Ranking disclosure",
+      "description": "The statutory ranking page in the default skin: every scorer with its weight, the sorts it applies to, and — for a scorer the deployment's engine cannot evaluate — the reason it is inactive, so the disclosure describes the ranking that actually ran rather than the one that was configured.",
+      "component": "RankingDisclosurePane",
+      "covers": [
+        "RankingDisclosure"
+      ],
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "desktop",
+        "phone"
+      ],
+      "source": "demo/RankingDisclosurePane.demo.tsx"
+    },
+    {
+      "id": "search.result-card",
+      "title": "Result card",
+      "description": "The default card a doc type gets for free: a 4:3 photo well drawn before the network answers (via @stapel/image, so a dead URL is a named placeholder rather than a torn-page icon), the title, the price with its currency, the location and distance — and the promoted marking painted from a token role rather than an antd preset, with its explanation as ordinary text beneath it.",
+      "component": "SearchResultCard",
+      "tokens": [
+        "warning-bg",
+        "warning-on",
+        "warning-border",
+        "surface-sunken"
+      ],
+      "variants": [
+        "promoted",
+        "plain"
+      ],
+      "source": "demo/SearchResultCard.demo.tsx"
+    },
+    {
+      "id": "search.results-pane",
+      "title": "Results pane",
+      "description": "One keyset page in the default skin: a counted heading (a capped count reads 'N+', never a flat number the server did not promise), the degradation banner, an auto-fill card grid, and a pager that is ABSENT when there is nothing to page rather than disabled with its reason in a tooltip.",
+      "component": "SearchResultsPane",
+      "covers": [
+        "SearchResults"
+      ],
+      "tokens": [
+        "surface-raised",
+        "warning-bg"
+      ],
+      "variants": [
+        "desktop",
+        "phone",
+        "empty"
+      ],
+      "source": "demo/SearchResultsPane.demo.tsx"
+    },
+    {
+      "id": "search.sort-select",
+      "title": "Sort control",
+      "description": "The five shipped sorts, plus whatever unknown sort a shared link already carries — offered rather than silently reset, because resetting it would rewrite the meaning of somebody's link on load and the server is the one entitled to refuse an unknown sort by name.",
+      "component": "SortSelect",
+      "tokens": [
+        "surface-raised"
+      ],
+      "variants": [
+        "no-centre",
+        "with-centre"
+      ],
+      "source": "demo/SortSelect.demo.tsx"
+    },
+    {
+      "id": "search.url-issue-notice",
+      "title": "Unreadable link notice",
+      "description": "The parameters a shared link carried that the codec could not read, named one by one. The alternative is not 'no notice' but a quietly WIDER search than the one that was shared, which is the difference between a page that is wrong and a page that says which part of the link it lost.",
+      "component": "UrlIssueNotice",
       "tokens": [
         "surface-raised"
       ],
       "variants": [
-        "default"
+        "two-issues",
+        "one-issue"
       ],
-      "source": "demo/SearchResults.demo.tsx"
+      "source": "demo/UrlIssueNotice.demo.tsx"
     }
   ],
   "i18nKeys": [
@@ -491,6 +662,14 @@
     "error.500.internal",
     "error.503.mandate_unavailable",
     "error.503.search_backend_unavailable",
+    "search.box.clear",
+    "search.box.label",
+    "search.box.placeholder",
+    "search.box.submit",
+    "search.box.suggestions",
+    "search.category.clear",
+    "search.category.current",
+    "search.category.title",
     "search.degraded.category_rollup",
     "search.degraded.exact_facet_counts",
     "search.degraded.exact_total",
@@ -509,15 +688,34 @@
     "search.facets.loading",
     "search.facets.not_counted",
     "search.facets.range_apply",
+    "search.facets.range_clear",
     "search.facets.range_from",
+    "search.facets.range_from_aria",
+    "search.facets.range_invalid",
     "search.facets.range_to",
+    "search.facets.range_to_aria",
     "search.facets.skipped",
     "search.facets.title",
+    "search.filters.apply",
+    "search.filters.dismiss",
+    "search.filters.open",
+    "search.filters.show_count",
+    "search.filters.show_count.one",
+    "search.filters.show_count.other",
+    "search.filters.show_count_at_least",
+    "search.filters.show_count_at_least.one",
+    "search.filters.show_count_at_least.other",
     "search.geo.box",
     "search.geo.center",
     "search.geo.clear",
     "search.geo.radius_km",
+    "search.geo.radius_label",
     "search.geo.title",
+    "search.language.any",
+    "search.language.label",
+    "search.limit.from_link",
+    "search.limit.label",
+    "search.limit.option",
     "search.ranking.applies_to",
     "search.ranking.empty",
     "search.ranking.inactive",
@@ -534,11 +732,15 @@
     "search.results.count_approximate",
     "search.results.count_approximate.one",
     "search.results.count_approximate.other",
+    "search.results.count_at_least",
+    "search.results.count_at_least.one",
+    "search.results.count_at_least.other",
     "search.results.count_exact",
     "search.results.count_exact.one",
     "search.results.count_exact.other",
     "search.results.distance_km",
     "search.results.empty",
+    "search.results.image_alt",
     "search.results.load_failed",
     "search.results.loading",
     "search.results.next",
@@ -568,29 +770,42 @@
     "runtime": [
       "FILTER_PREFIX",
       "FacetPanel",
+      "RANGE_FEATURE_TYPES",
       "RANGE_PREFIX",
       "RankingDisclosure",
       "SEARCH_BACKEND_UNAVAILABLE",
+      "SEARCH_BOX_DEBOUNCE_MS",
+      "SEARCH_BOX_SUGGEST_DEBOUNCE_MS",
+      "SEARCH_DEFAULT_PAGE_SIZE",
       "SEARCH_ERRORS",
       "SEARCH_ERROR_CODES",
       "SEARCH_I18N_KEYS",
       "SEARCH_I18N_PLURAL_KEYS",
+      "SEARCH_MAX_PAGE_SIZE",
       "SEARCH_PARAM",
+      "SEARCH_QUERY_MAX_CHARS",
       "SEARCH_SORTS",
       "SEARCH_WINDOW_EXCEEDED",
+      "SUGGEST_MAX_LIMIT",
+      "SUGGEST_MIN_CHARS",
       "SearchProvider",
       "SearchResults",
       "SearchRuntimeContext",
       "SearchStateProvider",
       "activeFilterCount",
       "buildFacetGroups",
+      "buildRangeGroups",
       "clearFilters",
       "countIsEstimate",
+      "countKind",
       "createSearchApi",
       "createSearchRuntime",
       "degradationMessageKey",
       "explainSearchError",
       "facetOptionLabel",
+      "isCountNuanceOnly",
+      "isRangeFeature",
+      "isRangeUsable",
       "navEntries",
       "ownsParam",
       "parseDegradations",
@@ -605,16 +820,20 @@
       "setRangeValue",
       "toggleFilterValue",
       "useAppliedSort",
+      "useFacetPanel",
       "useRankingDisclosure",
       "useSearchAnalytics",
       "useSearchApi",
+      "useSearchBox",
       "useSearchQuery",
       "useSearchRuntime",
       "useSearchState",
+      "useSuggest",
       "writeSearchState"
     ],
     "types": [
       "BuildFacetGroupsInput",
+      "BuildRangeGroupsInput",
       "CreateSearchRuntimeOptions",
       "FacetGroup",
       "FacetMeta",
@@ -623,12 +842,15 @@
       "FacetSelection",
       "ParseSearchStateOptions",
       "ParsedSearchState",
+      "RangeGroup",
       "RankingDisclosureBag",
       "RankingResponse",
       "Remediation",
       "Schemas",
       "Scorer",
       "SearchApi",
+      "SearchBoxBag",
+      "SearchCountKind",
       "SearchDegradation",
       "SearchDegradationKind",
       "SearchErrorCode",
@@ -652,7 +874,8 @@
       "SearchStatePatch",
       "SearchStateProviderProps",
       "SuggestParams",
-      "SuggestResponse"
+      "SuggestResponse",
+      "UseSearchBoxOptions"
     ]
   }
 }

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/search-react",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "entries": [
     {
       "id": "search.results",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -57,9 +57,9 @@
       "limit": "10 KB"
     },
     {
-      "name": "default — the antd skin (results, facet panel, degradation notice, ranking disclosure) must stay out of the main bundle",
+      "name": "default — the antd skin (query box + typeahead, filters incl. ranges/geo/category slots, results, ranking) must stay out of the main bundle",
       "path": "dist/default/index.js",
-      "limit": "13 KB"
+      "limit": "16 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -79,14 +79,18 @@
   ],
   "peerDependencies": {
     "@stapel/attributes-react": ">=0.1.0",
-    "@stapel/core": ">=0.17.0 <1.0.0",
-    "@stapel/tokens-antd": ">=0.5.0",
+    "@stapel/core": ">=0.18.1 <1.0.0",
+    "@stapel/image": ">=0.3.0",
+    "@stapel/tokens-antd": ">=0.7.0",
     "@tanstack/react-query": "^5.0.0",
     "antd": ">=5.20.0 <7",
     "react": ">=19",
     "react-router": ">=7.0.0 <8"
   },
   "peerDependenciesMeta": {
+    "@stapel/image": {
+      "optional": true
+    },
     "@stapel/tokens-antd": {
       "optional": true
     },
@@ -111,11 +115,12 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.2.0",
-    "@stapel/core": "^0.17.0",
-    "@stapel/showcase": "^0.2.0",
-    "@stapel/tokens": "^0.5.0",
-    "@stapel/tokens-antd": "^0.5.0"
+    "@stapel/image": "^0.4.1",
+    "@stapel/showcase": "^0.3.0",
+    "@stapel/core": "^0.18.1",
+    "@stapel/tokens": "^0.5.1",
+    "@stapel/attributes-react": "^0.3.1",
+    "@stapel/tokens-antd": "^0.7.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -213,7 +213,11 @@ export interface components {
             prev_anchor: string | null;
             has_next: boolean;
             has_prev: boolean;
-            count: number;
+            /** @description How many documents match. NEVER 0 beside a non-empty items[] — the answer may not claim fewer matches than the page shows. `null` means the engine cannot say, and is rendered as no count at all. */
+            count: number | null;
+            /** @description True when `count` is a floor: at least this many match, possibly more (a capped count, a window-truncated engine answer). Render 'N+', never 'N'. */
+            count_is_lower_bound: boolean;
+            /** @description True when `count` is exact for THIS answer — equivalent to `count is not null and not count_is_lower_bound`. Per answer, not per engine: an engine without a guaranteed exact total still counts a small candidate set exactly. */
             exact_total: boolean;
             /** @description What the configured engine could not do for this query. */
             degraded: string[];

package/src/default/DegradationNotice.tsx

@@ -9,41 +9,111 @@
  * 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.
+ *
+ * ── Two deliberate ways NOT to shout ───────────────────────────────────────
+ *
+ * 1. **`exact_total` alone never raises a banner.** It is a count NUANCE, not
+ *    a failed search: the rows are right, and the single consequence — that
+ *    the total is a floor — is already spoken by the count as "N+". A warning
+ *    box over a perfectly good result page teaches the reader that the page
+ *    is broken, and a banner that cries wolf on every landing page is a
+ *    banner nobody reads on the day `category_rollup` appears in it. Beside
+ *    any other degradation it renders normally, because the list is then
+ *    describing an answer that really is degraded. See
+ *    {@link isCountNuanceOnly}.
+ * 2. **`variant`.** A catalogue page wants the banner; a landing page that
+ *    shows six cards under a hero has no room for a warning box and passes
+ *    `"inline"` (one quiet line) or `"off"`. `"off"` is a decision the
+ *    CONTAINER makes about ITS surface — the notice stays the default, and
+ *    nothing here silences a degradation for everyone.
  */
 import type { ReactElement } from "react";
-import { Alert, Typography } from "antd";
+import { Alert, Flex, Typography } from "antd";
+import { fontSize, spacing } from "@stapel/tokens";
 import { useT } from "@stapel/core";
 import type { SearchDegradation } from "../api/types.js";
+import { isCountNuanceOnly } from "../state/degradations.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
+/**
+ * How loudly a surface says what the engine could not do.
+ *
+ * - `"banner"` (default) — an antd warning `Alert` with one line per item.
+ * - `"inline"` — the same sentences as quiet secondary text, no box.
+ * - `"off"` — nothing. For a surface where the notice does not belong at all;
+ *   the container that turns it off owns saying so somewhere else.
+ */
+export type DegradationNoticeVariant = "banner" | "inline" | "off";
+
 export interface DegradationNoticeProps {
   readonly degradations: readonly SearchDegradation[];
+  readonly variant?: DegradationNoticeVariant;
+  /**
+   * Names a `scorer:` degradation's slug, when something on the page knows
+   * one. `<SearchResultsPane>` passes the ranking disclosure's own names
+   * (`useScorerNames`); with no answer the slug is printed, which is what a
+   * registry identifier is worth on its own.
+   */
+  readonly scorerName?: (slug: string) => string | undefined;
 }
 
 export function DegradationNotice(
   props: DegradationNoticeProps
 ): ReactElement | null {
   const t = useT();
+  const variant: DegradationNoticeVariant = props.variant ?? "banner";
+  if (variant === "off") return null;
   if (props.degradations.length === 0) return null;
+  // A count nuance is not a degraded search — the count already says "N+".
+  if (isCountNuanceOnly(props.degradations)) return null;
+
+  const say = (degradation: SearchDegradation): string => {
+    const slug = degradation.scorer;
+    return t(degradation.messageKey, {
+      scorer:
+        slug === undefined
+          ? ""
+          : (props.scorerName?.(slug) ?? slug),
+      raw: degradation.raw,
+    });
+  };
+
+  // NOT `type="secondary"` in the banner: antd paints a warning Alert in the
+  // theme's warning tint, and grey body text on it measured under 3:1 in the
+  // visual pass. Inside a coloured box the readable colour is the box's own
+  // text colour, which is what a plain `<Typography.Text>` inherits.
+  const lines = props.degradations.map((degradation) => (
+    <li key={degradation.raw} data-degradation={degradation.raw}>
+      <Typography.Text>{say(degradation)}</Typography.Text>
+    </li>
+  ));
+
+  if (variant === "inline") {
+    return (
+      <Flex vertical gap={spacing[1]} data-testid="search-degraded" data-variant="inline">
+        <Typography.Text type="secondary" style={{ fontSize: fontSize.xs.fontSize }}>
+          {t(SEARCH_I18N_KEYS.degradedTitle)}
+        </Typography.Text>
+        <ul style={{ margin: 0, paddingInlineStart: spacing[5], fontSize: fontSize.xs.fontSize }}>
+          {props.degradations.map((degradation) => (
+            <li key={degradation.raw} data-degradation={degradation.raw}>
+              <Typography.Text type="secondary">{say(degradation)}</Typography.Text>
+            </li>
+          ))}
+        </ul>
+      </Flex>
+    );
+  }
+
   return (
     <Alert
       type="warning"
       showIcon
       data-testid="search-degraded"
-      message={t(SEARCH_I18N_KEYS.degradedTitle)}
+      data-variant="banner"
+      title={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>
+        <ul style={{ margin: 0, paddingInlineStart: spacing[5] }}>{lines}</ul>
       }
     />
   );