@stapel/search-react 0.25.0 → 0.26.0

package/src/api/types.ts

@@ -24,11 +24,17 @@ export type Schemas = components["schemas"];
  * slug either; ABSENT is a server too old to send one, and both read the same
  * way here (fall through to the schema).
  *
- * WHAT THE GENERATOR LOST: the field is newer than this pair's pinned
- * `schema.json`, so it is declared here as optional-and-nullable rather than
- * regenerated into a shape a deployed older server does not send.
+ * WHY IT IS NOT THE GENERATED SHAPE: stapel-search 0.14.5's `schema.json`
+ * declares this field REQUIRED, but the contract this pair announces is
+ * `>=0.14 <0.15`, and a 0.14.0 server inside that range sends no `label` at
+ * all. The generated member is therefore `Omit`ted and re-declared here as
+ * optional-and-nullable — a type must not promise a field a server the pair
+ * says it supports does not send.
  */
-export type FacetLabels = Schemas["FacetLabels"] & {
+export type FacetLabels = Omit<
+  Schemas["FacetLabels"],
+  "label" | "label_translatable" | "url_key"
+> & {
   readonly label?: string | null;
   /**
    * Whether {@link label} is a translation KEY rather than a caption, the way
@@ -43,6 +49,38 @@ export type FacetLabels = Schemas["FacetLabels"] & {
    * fixture captured from the wire is not a type error.
    */
   readonly label_translatable?: boolean;
+  /**
+   * What this group is called IN THE ADDRESS: `f.<url_key>`, `r.<url_key>`.
+   *
+   * The slug minus the type suffix an importer mints (`_select`,
+   * `_ref_select`, `_int`, `_bool`, `_string`) where dropping it stays
+   * unambiguous among the features of the category in scope, and the slug
+   * itself otherwise — and always when the query names no category
+   * (stapel-search 0.14.4+, `facets.url_keys`). Derived per request, never
+   * stored: the slug remains the feature's identity and both forms are
+   * accepted inside the scope, which is what lets a client write the short
+   * one without a migration behind it.
+   *
+   * WHY IT IS NOT THE GENERATED SHAPE: 0.14.5 declares it REQUIRED, and the
+   * announced contract is `>=0.14 <0.15` — a 0.14.0 server in that range
+   * states no `url_key`, and the codec's whole point is that such a link
+   * still works. `Omit`ted from the generated member and re-declared
+   * optional here. Measured on a live answer 2026-09-04:
+   * `make_ref_select` → `make`, `fuel_type_ref_select` → `fuel_type`,
+   * `model` → `model`.
+   */
+  readonly url_key?: string | null;
+  /**
+   * The vocabulary this group's values are drawn from, when the server names
+   * one.
+   *
+   * The one fact that decides whether an axis is a DICTIONARY rather than a
+   * list, and the client's second-best source for it: the first is the
+   * category schema's own `optionsRef`, which a host that threaded no schema
+   * does not have. Absent on every server that does not state it — absence
+   * is not "inline", it is "unsaid", and the schema is asked next.
+   */
+  readonly vocabulary?: string | null;
 };
 
 /** `facet_labels` as a whole: `{slug: {label, translatable, values}}`. */

package/src/default/FacetGroupControl.tsx

@@ -67,12 +67,9 @@ import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
 import { controls, cssVar, radii, spacing } from "@stapel/tokens";
-import {
-  VOCABULARY_BACKED_TYPES,
-  featureConfig,
-  featureType,
-} from "@stapel/attributes-react";
+import { featureConfig, featureType } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
+import { facetGroupIsVocabularyBacked } from "../state/facets.js";
 import type { FacetGroup, FacetOption } from "../state/facets.js";
 import { translitPrefixMatch } from "../state/translit.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
@@ -147,14 +144,21 @@ function singleChoice(feature: FeatureDef | undefined): boolean {
 }
 
 /**
- * Is this group a DICTIONARY — a vocabulary's level, too long to scroll?
+ * Is this group a DICTIONARY — an axis whose values live in a vocabulary?
  *
- * Two ways to be one, because the schema is an optional slot and the live
- * case is the one where it is empty:
+ * Two ways to be one, and only the second one counts anything:
  *
- *  - the def types the slug `ref_select`/`ref_hierarchical_select`, i.e. its
- *    config is a POINTER into a vocabulary and there was never an option
- *    table to draw;
+ *  - the axis is VOCABULARY-BACKED (`facetGroupIsVocabularyBacked`): the def
+ *    types it `ref_select`/`ref_hierarchical_select`, so its config is a
+ *    POINTER and there was never an option table to draw — or there is no def
+ *    and the answer named the vocabulary itself. **However many buckets came
+ *    back.** This threshold used to be counted against the answer's evidence,
+ *    and on a stand holding three cars the make axis has three buckets, drew
+ *    three checkboxes, and hid the other four hundred makes behind nothing at
+ *    all: the founder's "what if there are hundreds of options" is a question about the DICTIONARY,
+ *    and the dictionary is large whether or not this leaf has stock. The
+ *    field is also the only control that can search values the answer never
+ *    enumerated, which is exactly the case a thin stand produces;
  *  - there is NO def at all and the answer came back with more values than a
  *    fold. At a live classified's cars branch the storefront passed an empty
  *    feature list, so the 418 makes arrived as an unnamed, untyped group of
@@ -162,20 +166,20 @@ function singleChoice(feature: FeatureDef | undefined): boolean {
  *    answers that, and refusing to draw one because the schema is missing
  *    punishes the buyer for the wiring.
  *
- * Either way it takes more than {@link FACET_DICTIONARY_THRESHOLD} EVIDENCE
- * buckets — values the answer actually counted. A zero-filled option table or
- * a schema-only tail is a list a person can already read, and a box over it
- * would search for values no document carries.
+ * An INLINE option set is never one, whatever its length: a `select` carries
+ * its own table, that table is the whole of the axis, and a small one
+ * (≤ {@link FACET_DICTIONARY_THRESHOLD} options) is a list a person reads at
+ * a glance rather than types into.
  */
 export function isDictionaryFacet(group: FacetGroup): boolean {
+  if (facetGroupIsVocabularyBacked(group)) return true;
+  // A typed def that is not vocabulary-backed carries its options inline:
+  // checkboxes or pills, however many there are.
+  if (group.feature !== undefined) return false;
   const buckets = group.options.filter(
     (option) => option.count !== null && option.count > 0
   ).length;
-  if (buckets <= FACET_DICTIONARY_THRESHOLD) return false;
-  const feature = group.feature;
-  if (feature === undefined) return true;
-  const type = featureType(feature);
-  return type !== undefined && VOCABULARY_BACKED_TYPES.includes(type);
+  return buckets > FACET_DICTIONARY_THRESHOLD;
 }
 
 /**
@@ -189,9 +193,9 @@ export function isDictionaryFacet(group: FacetGroup): boolean {
  *    `maxSelected: 1` over a 418-value vocabulary, so "pick one" won and the
  *    control it produced was four hundred pills in a 280px rail — a wall
  *    with a different border radius. Above the fold the shape a person needs
- *    is a search box, whether or not they may tick two; below it,
- *    single-choice still means pills, because `isDictionaryFacet` requires
- *    more than {@link FACET_DICTIONARY_THRESHOLD} counted buckets;
+ *    is a search box, whether or not they may tick two. A single-choice axis
+ *    with an INLINE option table still means pills, because a dictionary is
+ *    now about where the values live and not about how many came back;
  *  - and a dictionary is a dictionary before it is a checkbox list, because
  *    the checkbox list is the shape it was drawn as when nobody could pick a
  *    make.

package/src/default/FacetPanelPane.tsx

@@ -260,17 +260,28 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
    */
   readonly skippedNotice?: boolean;
   /**
-   * Draw the sticky footer inside the panel: the live result count as the
-   * bar's strong text, and the clear-all control (which then moves out of the
-   * heading row — one control, not two) beside it. Default `false`.
+   * Draw the footer inside the panel: the live result count as the bar's
+   * strong text, and the clear-all control (which then moves out of the
+   * heading row — one control, not two) beside it. Default: no bar.
    *
    * `<SearchPage>` turns it on for the desktop RAIL only. Desktop filters
    * apply instantly, so the bar is FEEDBACK plus the way out, not an apply
    * button — which is exactly why the phone sheet must not get it: the sheet
    * already closes through its own "Show N results" footer, and a second
    * count-bearing bar above that one would be the same sentence twice.
+   *
+   * ── Where it sits, and why that is a choice ───────────────────────────────
+   *
+   * `"sticky"` (and `true`, which is what it has always meant) pins the bar to
+   * the bottom of the panel's own scroll port. That is right in a SHEET, whose
+   * port is the sheet and whose bar is the way out of it. In the desktop
+   * COLUMN the rail scrolls with the page, so an opaque bar pinned to the
+   * bottom of the viewport parks itself over the last two facet groups and
+   * they cannot be reached at all — a storefront was reaching for `!important`
+   * to lift it off. `"static"` puts the bar after the groups, where it stops
+   * covering anything, and the column layout of `<SearchPage>` passes it.
    */
-  readonly footerBar?: boolean;
+  readonly footerBar?: boolean | "sticky" | "static";
   /**
    * The partition control, drawn at the TOP of the panel — above the price,
    * above every facet.
@@ -319,6 +330,9 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
 function RailFooterBar(props: {
   readonly activeFilters: number;
   readonly clearAll: () => void;
+  /** `"sticky"` pins it to the scroll port's floor; `"static"` lets it sit
+   * after the last group. See {@link FacetPanelPaneProps.footerBar}. */
+  readonly position: "sticky" | "static";
 }): ReactElement | null {
   const t = useT();
   const tPlural = useTPlural();
@@ -340,9 +354,9 @@ function RailFooterBar(props: {
   return (
     <div
       data-testid="facets-footer-bar"
+      data-position={props.position}
       style={{
-        position: "sticky",
-        bottom: 0,
+        ...(props.position === "sticky" ? { position: "sticky", bottom: 0 } : {}),
         // Opaque, or the options scrolling under the bar read THROUGH it.
         background: token.colorBgContainer,
         borderBlockStart: `1px solid ${token.colorSplit}`,
@@ -513,6 +527,13 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
   // panel's own search box: the URL is the search, and how much of the rail a
   // person has unfolded is not part of it.
   const [tailOpen, setTailOpen] = useState(false);
+  // `true` is the shape the prop shipped with and keeps meaning: pinned.
+  const footerBar: "sticky" | "static" | "none" =
+    props.footerBar === true
+      ? "sticky"
+      : props.footerBar === false || props.footerBar === undefined
+        ? "none"
+        : props.footerBar;
 
   return (
     <SkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
@@ -577,7 +598,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               {/* With the footer bar on, clear-all lives THERE — beside the
                   count it acts on — and drawing it here too would be two
                   identical exits one panel apart. */}
-              {bag.activeFilters > 0 && props.footerBar !== true && (
+              {bag.activeFilters > 0 && footerBar === "none" && (
                 <Button
                   style={FACET_CLEAR}
                   onClick={bag.clearAll}
@@ -845,10 +866,11 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               </>
             )}
 
-            {props.footerBar === true && (
+            {footerBar !== "none" && (
               <RailFooterBar
                 activeFilters={bag.activeFilters}
                 clearAll={bag.clearAll}
+                position={footerBar}
               />
             )}
           </Flex>

package/src/default/SearchPage.tsx

@@ -261,6 +261,22 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
   /** Facet slugs pinned above every other group — see
    * {@link FacetPanelPaneProps.pinnedFacets}. */
   readonly pinnedFacets?: readonly string[];
+  /**
+   * How a DICTIONARY group is drawn — see
+   * {@link FacetPanelPaneProps.dictionaryMode}.
+   *
+   * Defaulted PER LAYOUT rather than left to the panel's own default, because
+   * the two frames want opposite shapes and only this component knows which
+   * one it is drawing: the desktop rail gets `"field"` (a select-style «Any»
+   * that opens the searchable list — a 418-value vocabulary held open in a
+   * 280px column is the whole column), the phone sheet gets `"inline"`
+   * (the sheet is already the disclosure). Set it to override both.
+   *
+   * It was unreachable through this component until now: the panel had the
+   * prop, `<SearchPage>` forwarded nothing, and a storefront that mounts the
+   * page rather than the pane could not get the field at all.
+   */
+  readonly dictionaryMode?: "field" | "inline";
   /** Print the engine's list of uncounted facet slugs in the filter panel.
    * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
   readonly skippedNotice?: boolean;
@@ -422,6 +438,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
+  readonly dictionaryMode?: "field" | "inline";
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly renderEmptyExits?: () => ReactNode;
   readonly locale?: string;
@@ -545,7 +562,12 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           result count scrolled out of sight above the fold. */}
       {filtersEmpty ? null : (
         <FacetPanelPane
-          {...(layout === "sheet" ? { heading: null } : { footerBar: true })}
+          {...(layout === "sheet"
+            ? { heading: null }
+            : // STATIC, not sticky: the rail scrolls with the page, and a bar
+              // pinned to the port's floor sat on top of the last groups.
+              { footerBar: "static" as const })}
+          dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "inline" : "field")}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(props.renderEmptyExits !== undefined
             ? { renderEmptyExits: props.renderEmptyExits }
@@ -805,6 +827,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     onViewChange,
     resultsAction,
     resultsHeadingLevel,
+    dictionaryMode,
     mode,
     ...parseOptions
   } = props;
@@ -814,6 +837,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
       <SearchStateProvider adapter={adapter} geoOffer={geoOffer} {...parseOptions}>
         <SearchPageBody
           {...(renderCard !== undefined ? { renderCard } : {})}
+          {...(dictionaryMode !== undefined ? { dictionaryMode } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(locale !== undefined ? { locale } : {})}
           {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}

package/src/headless/SearchStateProvider.tsx

@@ -2,17 +2,22 @@ import {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useState,
 } from "react";
 import type { ReactElement, ReactNode } from "react";
 import type {
+  FacetLabelsMap,
   SearchGeo,
   SearchQueryState,
   SearchRange,
 } from "../api/types.js";
 import {
+  EMPTY_FACET_KEYS,
   activeFilterCount,
   clearFilters,
+  facetKeyMapFromLabels,
   parseSearchState,
   patchSearchState,
   setFilterValues,
@@ -21,6 +26,7 @@ import {
   writeSearchState,
 } from "../state/urlState.js";
 import type {
+  FacetKeyMap,
   ParseSearchStateOptions,
   SearchStateIssue,
   SearchStatePatch,
@@ -132,6 +138,56 @@ function sameCenter(
 
 const StateContext = createContext<SearchStateBag | null>(null);
 
+/**
+ * WHERE THE SHORT KEYS COME FROM.
+ *
+ * `f.make` is a fact of the ANSWER (`facet_labels[slug].url_key`, resolved by
+ * the server inside the queried category's scope), and the codec that writes
+ * the address runs above the query that produces it. So the map is published
+ * upwards: whoever holds an answer hands it to this provider, which re-parses
+ * the URL with it and writes every subsequent address through it.
+ *
+ * Late by construction and correct at every moment in between: before the
+ * first answer the state holds whatever key the link carried, the request
+ * carries the same key, and the server resolves both forms. Nothing waits and
+ * nothing is rewritten behind the reader.
+ */
+interface FacetKeyRegistry {
+  readonly keys: FacetKeyMap;
+  publish(next: FacetKeyMap): void;
+}
+
+const FacetKeysContext = createContext<FacetKeyRegistry | null>(null);
+
+/** Two maps are the same map when they write the same keys — the read side is
+ * derived from the write side, so comparing one compares both. */
+function sameKeys(a: FacetKeyMap, b: FacetKeyMap): boolean {
+  const left = Object.keys(a.write);
+  const right = Object.keys(b.write);
+  if (left.length !== right.length) return false;
+  return left.every((slug) => a.write[slug] === b.write[slug]);
+}
+
+/**
+ * Publish an answer's short keys to the state provider above.
+ *
+ * A no-op outside `<SearchStateProvider>` and a no-op on a server that sends
+ * no `url_key`: both leave the address spelled in slugs, which is what it was
+ * spelled in before this existed.
+ */
+export function usePublishFacetKeys(labels: FacetLabelsMap | undefined): void {
+  const registry = useContext(FacetKeysContext);
+  useEffect(() => {
+    if (registry === null || labels === undefined) return;
+    registry.publish(facetKeyMapFromLabels(labels));
+  }, [registry, labels]);
+}
+
+/** The short-key map this search is currently writing its address with. */
+export function useFacetKeys(): FacetKeyMap {
+  return useContext(FacetKeysContext)?.keys ?? EMPTY_FACET_KEYS;
+}
+
 export interface SearchStateProviderProps extends ParseSearchStateOptions {
   readonly adapter: SearchParamsAdapter;
   /**
@@ -193,9 +249,27 @@ export function SearchStateProvider(
 
   const search = params.toString();
 
+  // The answer's short keys (`f.make`), published from below — see
+  // `FacetKeysContext`. Held here because this is where both directions of
+  // the codec run.
+  const [facetKeys, setFacetKeys] = useState<FacetKeyMap>(EMPTY_FACET_KEYS);
+  const registry = useMemo<FacetKeyRegistry>(
+    () => ({
+      keys: facetKeys,
+      publish: (next) => {
+        // Idempotent on purpose: this is called from an effect under a query
+        // whose data identity is stable, and a setState that always produced
+        // a new object would re-render the whole page per answer.
+        setFacetKeys((was) => (sameKeys(was, next) ? was : next));
+      },
+    }),
+    [facetKeys]
+  );
+
   const parsed = useMemo(
     () =>
       parseSearchState(new URLSearchParams(search), {
+        facetKeys,
         defaultType,
         ...(defaultQ !== undefined ? { defaultQ } : {}),
         ...(defaultSort !== undefined ? { defaultSort } : {}),
@@ -203,14 +277,26 @@ export function SearchStateProvider(
         ...(defaultCategory !== undefined ? { defaultCategory } : {}),
         ...(defaultLang !== undefined ? { defaultLang } : {}),
       }),
-    [search, defaultType, defaultQ, defaultSort, defaultLimit, defaultCategory, defaultLang]
+    [
+      search,
+      facetKeys,
+      defaultType,
+      defaultQ,
+      defaultSort,
+      defaultLimit,
+      defaultCategory,
+      defaultLang,
+    ]
   );
 
   const commit = useCallback(
     (next: SearchQueryState, options?: { readonly replace?: boolean }): void => {
-      setParams(writeSearchState(next, new URLSearchParams(search)), options);
+      setParams(
+        writeSearchState(next, new URLSearchParams(search), facetKeys),
+        options
+      );
     },
-    [setParams, search]
+    [setParams, search, facetKeys]
   );
 
 
@@ -280,7 +366,11 @@ export function SearchStateProvider(
   }, [parsed, commit, geoOffer]);
 
 
-  return <StateContext.Provider value={bag}>{children}</StateContext.Provider>;
+  return (
+    <FacetKeysContext.Provider value={registry}>
+      <StateContext.Provider value={bag}>{children}</StateContext.Provider>
+    </FacetKeysContext.Provider>
+  );
 }
 
 /**

package/src/i18n/generated/errors.es.gen.ts

@@ -35,6 +35,7 @@ export const searchErrorBundleEs: Record<SearchErrorCode, string> = {
   "error.400.search_sort_needs_center": "Ordenar por distancia requiere lat y lon",
   "error.400.search_too_many_facets": "Demasiados filtros de faceta (límite {limit})",
   "error.400.search_too_many_ranges": "Demasiados filtros de rango (límite {limit})",
+  "error.400.search_unknown_category": "No existe la categoría «{category}». `category` admite el id del nodo o su ruta raíz/hoja.",
   "error.400.search_unknown_doc_type": "Tipo de búsqueda desconocido «{doc_type}»",
   "error.400.search_unknown_sort": "Orden desconocido «{sort}»",
   "error.400.search_window_exceeded": "Esta página de resultados supera el límite de {window}. Acote la búsqueda en lugar de avanzar más páginas.",

package/src/i18n/generated/errors.gen.ts

@@ -58,6 +58,7 @@ export const SEARCH_ERRORS = {
   "error.400.search_sort_needs_center": { status: 400, params: [], remediation: "fix_input", en: "Sorting by distance needs lat and lon" },
   "error.400.search_too_many_facets": { status: 400, params: ["limit"], remediation: "fix_input", en: "Too many facet filters (limit {limit})" },
   "error.400.search_too_many_ranges": { status: 400, params: ["limit"], remediation: "fix_input", en: "Too many range filters (limit {limit})" },
+  "error.400.search_unknown_category": { status: 400, params: ["category"], remediation: "fix_input", en: "No category '{category}' exists. `category` takes the node id or its root/leaf path." },
   "error.400.search_unknown_doc_type": { status: 400, params: ["doc_type"], remediation: "fix_input", en: "Unknown search type '{doc_type}'" },
   "error.400.search_unknown_sort": { status: 400, params: ["sort"], remediation: "fix_input", en: "Unknown sort '{sort}'" },
   "error.400.search_window_exceeded": { status: 400, params: ["window"], remediation: "fix_input", en: "This result page is beyond the maximum window of {window}. Narrow the search instead of paging deeper." },
@@ -118,6 +119,7 @@ export const SEARCH_ERROR_CODES: readonly SearchErrorCode[] = [
   "error.400.search_sort_needs_center",
   "error.400.search_too_many_facets",
   "error.400.search_too_many_ranges",
+  "error.400.search_unknown_category",
   "error.400.search_unknown_doc_type",
   "error.400.search_unknown_sort",
   "error.400.search_window_exceeded",
@@ -180,6 +182,7 @@ export const searchErrorBundleEn: Record<SearchErrorCode, string> = {
   "error.400.search_sort_needs_center": "Sorting by distance needs lat and lon",
   "error.400.search_too_many_facets": "Too many facet filters (limit {limit})",
   "error.400.search_too_many_ranges": "Too many range filters (limit {limit})",
+  "error.400.search_unknown_category": "No category '{category}' exists. `category` takes the node id or its root/leaf path.",
   "error.400.search_unknown_doc_type": "Unknown search type '{doc_type}'",
   "error.400.search_unknown_sort": "Unknown sort '{sort}'",
   "error.400.search_window_exceeded": "This result page is beyond the maximum window of {window}. Narrow the search instead of paging deeper.",

package/src/i18n/generated/errors.json

@@ -195,6 +195,15 @@
     "remediation": "fix_input",
     "en": "Too many range filters (limit {limit})"
   },
+  {
+    "code": "error.400.search_unknown_category",
+    "status": 400,
+    "params": [
+      "category"
+    ],
+    "remediation": "fix_input",
+    "en": "No category '{category}' exists. `category` takes the node id or its root/leaf path."
+  },
   {
     "code": "error.400.search_unknown_doc_type",
     "status": 400,

package/src/i18n/generated/errors.ru.gen.ts

@@ -35,6 +35,7 @@ export const searchErrorBundleRu: Record<SearchErrorCode, string> = {
   "error.400.search_sort_needs_center": "Сортировка по расстоянию требует координат (lat и lon)",
   "error.400.search_too_many_facets": "Слишком много фильтров-фасетов (предел {limit})",
   "error.400.search_too_many_ranges": "Слишком много диапазонных фильтров (предел {limit})",
+  "error.400.search_unknown_category": "Категории «{category}» не существует. В `category` передаётся id узла или путь корень/лист.",
   "error.400.search_unknown_doc_type": "Неизвестный тип поиска «{doc_type}»",
   "error.400.search_unknown_sort": "Неизвестная сортировка «{sort}»",
   "error.400.search_window_exceeded": "Эта страница выдачи выходит за предел в {window} результатов. Уточните запрос вместо перелистывания вглубь.",

package/src/index.ts

@@ -77,11 +77,16 @@ export type {
 
 // ── state (pure: no React, no router) ────────────────────────────────────────
 export {
+  EMPTY_FACET_KEYS,
   FILTER_PREFIX,
   RANGE_PREFIX,
   SEARCH_PARAM,
   activeFilterCount,
+  buildFacetKeyMap,
   clearFilters,
+  facetKeyForSlug,
+  facetKeyMapFromLabels,
+  facetSlugForKey,
   ownsParam,
   parseSearchState,
   patchSearchState,
@@ -91,6 +96,7 @@ export {
   writeSearchState,
 } from "./state/urlState.js";
 export type {
+  FacetKeyMap,
   ParseSearchStateOptions,
   ParsedSearchState,
   SearchStateIssue,
@@ -118,6 +124,7 @@ export {
   buildFacetGroups,
   facetGroupHasEvidence,
   facetGroupIsDrawable,
+  facetGroupIsVocabularyBacked,
   facetOptionLabel,
   isFacetableFeature,
   orderFacetGroupsBySchema,
@@ -177,7 +184,12 @@ export { useRankingDisclosure, useSearchQuery, useSuggest } from "./model/querie
 
 // ── headless (renderless components) ─────────────────────────────────────────
 export { SearchProvider } from "./headless/SearchProvider.js";
-export { SearchStateProvider, useSearchState } from "./headless/SearchStateProvider.js";
+export {
+  SearchStateProvider,
+  useFacetKeys,
+  usePublishFacetKeys,
+  useSearchState,
+} from "./headless/SearchStateProvider.js";
 export type {
   SearchParamsAdapter,
   SearchStateBag,

package/src/model/queries.ts

@@ -9,6 +9,7 @@ import type {
   SuggestAnswer,
 } from "../api/types.js";
 import { SUGGEST_MAX_LIMIT, SUGGEST_MIN_CHARS } from "../state/limits.js";
+import { usePublishFacetKeys } from "../headless/SearchStateProvider.js";
 import { useSearchApi } from "./context.js";
 import { searchQueryKeys } from "./queryKeys.js";
 
@@ -53,13 +54,22 @@ export function useSearchQuery(
 ): UseQueryResult<SearchResponse, StapelApiError> {
   const api = useSearchApi();
   const params = searchQueryParams(state);
-  return useQuery({
+  const query = useQuery<SearchResponse, StapelApiError>({
     queryKey: searchQueryKeys.query(params),
     queryFn: ({ signal }) => api.query(state, { signal }),
     enabled: (options?.enabled ?? true) && state.type.length > 0,
     placeholderData: keepPreviousData,
     retry: false,
   });
+  // The answer states what each axis is called IN THE ADDRESS
+  // (`facet_labels[slug].url_key`); the codec that writes the address sits
+  // above this hook, so the map is handed up. Every surface reads through
+  // this one hook, so there is exactly one place the address learns its own
+  // spelling — and outside a `<SearchStateProvider>` it is a no-op.
+  usePublishFacetKeys(
+    query.data === undefined ? undefined : query.data.facet_labels
+  );
+  return query;
 }
 
 /**