@stapel/search-react 0.4.0 → 0.8.0

package/dist/state/ranges.d.ts

@@ -0,0 +1,52 @@
+import type { FeatureDef } from "@stapel/attributes-react";
+import type { SearchQueryState, SearchRange } from "../api/types.js";
+/**
+ * Value types a numeric range row is drawn for (`config.type`, the
+ * stapel-attributes value-type slug).
+ */
+export declare const RANGE_FEATURE_TYPES: readonly string[];
+/** One `r.<slug>` row of the filter panel. */
+export interface RangeGroup {
+    readonly slug: string;
+    /** The feature's display name (translated when it is a key), else the slug. */
+    readonly label: string;
+    /** The schema entry behind the slug, when the host supplied one. */
+    readonly feature: FeatureDef | undefined;
+    /** The applied bounds, exactly as the URL carries them (strings — the wire
+     * never promised a number, and re-formatting one would rewrite the link). */
+    readonly from: string | undefined;
+    readonly to: string | undefined;
+    /** Bounds the schema declares, for the input's own limits. */
+    readonly min: number | undefined;
+    readonly max: number | undefined;
+    /** Unit suffix the schema declares (`postfix`, or a convertible unit). */
+    readonly unit: string | undefined;
+    /** `1` for an integer feature — a whole-number input for a whole number. */
+    readonly step: number | undefined;
+    /** Whether the URL currently constrains this slug. */
+    readonly active: boolean;
+}
+export interface BuildRangeGroupsInput {
+    readonly state: SearchQueryState;
+    readonly categoryFeatures?: readonly FeatureDef[];
+    /** Translator for label keys (the schema's `name` is often one). */
+    readonly t?: (key: string) => string;
+}
+/** Is this feature one a numeric range row is drawn for? */
+export declare function isRangeFeature(feature: FeatureDef): boolean;
+/**
+ * The range rows for the current search: every numeric feature of the
+ * category, in the schema's own order, plus any slug the URL constrains that
+ * the schema does not explain.
+ */
+export declare function buildRangeGroups(input: BuildRangeGroupsInput): readonly RangeGroup[];
+/**
+ * Is a from/to pair one the server could ever match?
+ *
+ * `100..50` is syntactically fine and semantically empty, and the backend does
+ * not refuse it — it answers zero results, which reads as "there is nothing
+ * like this" rather than "you typed it backwards". So the panel refuses to
+ * apply it and says why, beside the button (`search.facets.range_invalid`).
+ */
+export declare function isRangeUsable(range: SearchRange): boolean;
+//# sourceMappingURL=ranges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ranges.d.ts","sourceRoot":"","sources":["../../src/state/ranges.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAIhD,CAAC;AAEF,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC;iFAC6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,oEAAoE;IACpE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AAgBD,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAG3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,GAC3B,SAAS,UAAU,EAAE,CA8BvB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAMzD"}

package/dist/state/ranges.js

@@ -0,0 +1,108 @@
+/**
+ * The RANGE half of the filter model — `r.<slug>=from..to`.
+ *
+ * The codec has carried ranges since 0.1 (`setRangeValue`, `RANGE_PREFIX`) and
+ * nothing ever drew one: a marketplace shipped without a price filter because
+ * the panel only knew how to draw checkboxes. This module is the missing half:
+ * which slugs a range row exists for, and what the row is called.
+ *
+ * ── Where a range row comes from, and why it is not the response ───────────
+ *
+ * A facet answer (`facets: {slug: {value: count}}`) enumerates DISCRETE values;
+ * a range is not enumerable and the server never sends one. So the rows come
+ * from the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
+ * checkboxes their labels — filtered to the numeric value types, plus every
+ * slug the URL already carries a range for.
+ *
+ * That last clause is the same rule `buildFacetGroups` follows for a filtered
+ * slug that fell out of the plan: a constraint that is ACTIVE must always have
+ * a control that removes it, even when the schema no longer explains it.
+ * Otherwise a shared link narrows the search with nothing on screen to widen it
+ * again.
+ *
+ * `date` is range-capable on the wire and is deliberately NOT here: a date
+ * range needs a date editor, the editor lives in `@stapel/attributes-react`'s
+ * registry, and a numeric input over a Unix timestamp would be worse than no
+ * control at all. The codec still round-trips one a host sets.
+ */
+import { featureConfig, featureName, featureType } from "@stapel/attributes-react";
+/**
+ * Value types a numeric range row is drawn for (`config.type`, the
+ * stapel-attributes value-type slug).
+ */
+export const RANGE_FEATURE_TYPES = [
+    "int",
+    "float",
+    "convertible_unit",
+];
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function translate(t, key) {
+    if (t === undefined)
+        return key;
+    const resolved = t(key);
+    return resolved.length > 0 ? resolved : key;
+}
+/** Is this feature one a numeric range row is drawn for? */
+export function isRangeFeature(feature) {
+    const type = featureType(feature);
+    return type !== undefined && RANGE_FEATURE_TYPES.includes(type);
+}
+/**
+ * The range rows for the current search: every numeric feature of the
+ * category, in the schema's own order, plus any slug the URL constrains that
+ * the schema does not explain.
+ */
+export function buildRangeGroups(input) {
+    const bySlug = new Map();
+    for (const feature of input.categoryFeatures ?? [])
+        bySlug.set(feature.slug, feature);
+    const slugs = [];
+    for (const feature of input.categoryFeatures ?? []) {
+        if (isRangeFeature(feature))
+            slugs.push(feature.slug);
+    }
+    for (const slug of Object.keys(input.state.ranges)) {
+        if (!slugs.includes(slug))
+            slugs.push(slug);
+    }
+    return slugs.map((slug) => {
+        const feature = bySlug.get(slug);
+        const config = feature === undefined ? {} : featureConfig(feature);
+        const applied = input.state.ranges[slug];
+        return {
+            slug,
+            label: feature === undefined ? slug : translate(input.t, featureName(feature)),
+            feature,
+            from: applied?.from,
+            to: applied?.to,
+            min: num(config["min"]),
+            max: num(config["max"]),
+            unit: str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"]),
+            step: feature !== undefined && featureType(feature) === "int" ? 1 : undefined,
+            active: applied !== undefined,
+        };
+    });
+}
+/**
+ * Is a from/to pair one the server could ever match?
+ *
+ * `100..50` is syntactically fine and semantically empty, and the backend does
+ * not refuse it — it answers zero results, which reads as "there is nothing
+ * like this" rather than "you typed it backwards". So the panel refuses to
+ * apply it and says why, beside the button (`search.facets.range_invalid`).
+ */
+export function isRangeUsable(range) {
+    if (range.from === undefined || range.to === undefined)
+        return true;
+    const from = Number(range.from);
+    const to = Number(range.to);
+    if (!Number.isFinite(from) || !Number.isFinite(to))
+        return true;
+    return from <= to;
+}
+//# sourceMappingURL=ranges.js.map

package/dist/state/ranges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranges.js","sourceRoot":"","sources":["../../src/state/ranges.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/search-react 0.4.0
+# @stapel/search-react 0.8.0
 
 Headless React flow pair for stapel-search (contract >=0.2 <0.3) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
@@ -30,6 +30,7 @@ Paths are relative to `/search/api/v1/`.
 ## Query hooks (server state; keys come only from the key factory)
 - useRankingDisclosure (query) → ranking
 - useSearchQuery (query) → query
+- useSuggest (query) → suggest
 
 ## Errors (render t(code, params); UX from remediation)
 54 keys (full catalog: manifest.json §errors). By remediation: fix_input 26 · retry 15 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
@@ -74,9 +75,20 @@ const { tracked } = useTracked();
 ```
 
 ## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
-- search.facets → <FacetPanel> [default]  demo/FacetPanel.demo.tsx
-- search.ranking → <RankingDisclosure> [default]  demo/RankingDisclosure.demo.tsx
-- search.results → <SearchResults> [default]  demo/SearchResults.demo.tsx
+- search.box → <SearchBox> [empty|typed]  demo/SearchBox.demo.tsx
+- search.classified-filters → <FilterChips> [chips|applied|shapes|views]  demo/ClassifiedFilters.demo.tsx
+- search.degradation-notice → <DegradationNotice> [banner|inline]  demo/DegradationNotice.demo.tsx
+- search.facet-panel-pane → <FacetPanelPane> [open-search|narrowed]  demo/FacetPanelPane.demo.tsx
+- search.filter-sheet → <SearchPage> [open]  demo/FilterSheet.demo.tsx
+- search.language-select → <LanguageSelect> [offered|from-a-link]  demo/LanguageSelect.demo.tsx
+- search.page → <SearchPage> [desktop|phone|unreadable-link]  demo/SearchPage.demo.tsx
+- search.page-size-select → <PageSizeSelect> [ladder|off-ladder]  demo/PageSizeSelect.demo.tsx
+- search.range-filter-row → <RangeFilterRow> [untouched|applied]  demo/RangeFilterRow.demo.tsx
+- search.ranking-pane → <RankingDisclosurePane> [desktop|phone]  demo/RankingDisclosurePane.demo.tsx
+- search.result-card → <SearchResultCard> [promoted|plain]  demo/SearchResultCard.demo.tsx
+- search.results-pane → <SearchResultsPane> [desktop|phone|empty]  demo/SearchResultsPane.demo.tsx
+- search.sort-select → <SortSelect> [no-centre|with-centre]  demo/SortSelect.demo.tsx
+- search.url-issue-notice → <UrlIssueNotice> [two-issues|one-issue]  demo/UrlIssueNotice.demo.tsx
 Each source file is the canonical usage snippet (open the default variant).
 
 ## Snippets

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.2 <0.3"
@@ -70,6 +70,17 @@
         "query",
         "{params}"
       ]
+    },
+    "useSuggest": {
+      "kind": "query",
+      "operation": "suggest",
+      "queryKey": [
+        "search",
+        "suggest",
+        "{type}",
+        "{q}",
+        "{…}"
+      ]
     }
   },
   "errors": {
@@ -393,47 +404,228 @@
   },
   "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.classified-filters",
+      "title": "Filter chips and group shapes",
+      "description": "The phone's filter row — one scrolling line of chips, each opening its own bottom sheet, with the whole panel behind the leading icon-only chip and a dot on it when something is applied. Beside it, the three shapes a facet group takes, all three DERIVED from the category schema rather than chosen per screen: pills for a single-choice facet, indented rows for a hierarchical one, and a fold for a long one that says how many are behind it.",
+      "component": "FilterChips",
+      "covers": [
+        "FacetGroupControl",
+        "ViewSwitch"
+      ],
+      "tokens": [
+        "surface-raised",
+        "brand"
+      ],
+      "variants": [
+        "chips",
+        "applied",
+        "shapes",
+        "views"
+      ],
+      "source": "demo/ClassifiedFilters.demo.tsx"
+    },
+    {
+      "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 +683,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 +709,39 @@
     "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.show_all",
+    "search.facets.show_less",
     "search.facets.skipped",
     "search.facets.title",
+    "search.filters.all",
+    "search.filters.apply",
+    "search.filters.chip_more",
+    "search.filters.chips_label",
+    "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",
@@ -542,6 +766,7 @@
     "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",
@@ -565,28 +790,40 @@
     "search.url.issue.geo_incomplete",
     "search.url.issue.not_a_number",
     "search.url.issue.range_malformed",
-    "search.url.issues_title"
+    "search.url.issues_title",
+    "search.view.grid",
+    "search.view.label",
+    "search.view.list"
   ],
   "exports": {
     "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",
@@ -596,6 +833,8 @@
       "explainSearchError",
       "facetOptionLabel",
       "isCountNuanceOnly",
+      "isRangeFeature",
+      "isRangeUsable",
       "navEntries",
       "ownsParam",
       "parseDegradations",
@@ -610,16 +849,20 @@
       "setRangeValue",
       "toggleFilterValue",
       "useAppliedSort",
+      "useFacetPanel",
       "useRankingDisclosure",
       "useSearchAnalytics",
       "useSearchApi",
+      "useSearchBox",
       "useSearchQuery",
       "useSearchRuntime",
       "useSearchState",
+      "useSuggest",
       "writeSearchState"
     ],
     "types": [
       "BuildFacetGroupsInput",
+      "BuildRangeGroupsInput",
       "CreateSearchRuntimeOptions",
       "FacetGroup",
       "FacetMeta",
@@ -628,12 +871,14 @@
       "FacetSelection",
       "ParseSearchStateOptions",
       "ParsedSearchState",
+      "RangeGroup",
       "RankingDisclosureBag",
       "RankingResponse",
       "Remediation",
       "Schemas",
       "Scorer",
       "SearchApi",
+      "SearchBoxBag",
       "SearchCountKind",
       "SearchDegradation",
       "SearchDegradationKind",
@@ -658,7 +903,8 @@
       "SearchStatePatch",
       "SearchStateProviderProps",
       "SuggestParams",
-      "SuggestResponse"
+      "SuggestResponse",
+      "UseSearchBoxOptions"
     ]
   }
 }

package/nav-manifest.json

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