@stapel/search-react 0.25.0 → 0.27.0

package/src/default/FacetPanelPane.tsx

@@ -181,15 +181,21 @@ export const FACET_OPEN_GROUPS = 5;
 export const FACET_SEARCH_THRESHOLD = 6;
 
 /**
- * How many groups the rail draws before the rest go behind one control.
+ * How many groups the rail draws before the rest go behind one control. This
+ * is `<FacetPanelPane>`'s own default, for the desktop COLUMN — `<SearchPage>`
+ * passes 8 for the phone sheet instead (a surface reached through a modal
+ * already costs a tap; folding its tail behind a second one is not the same
+ * saving as folding a column that sits on screen the whole time).
  *
- * The reference classified shows a make, a price, a year and a handful of
- * body axes, and then the word "all filters" — eight is the count that fills
- * a 900px rail once the partition row and the price have taken their share,
- * and it is the point past which a person is scanning rather than reading.
- * The tail is not hidden: `facetsAllFilters` names how many are in it.
+ * The reference classified inlines roughly two dozen groups in the desktop
+ * rail before anything folds — eight, this pair's number for three releases,
+ * turned a make, a price and a year into the whole visible rail with a
+ * "all filters" button under them. Sixteen is not a copy of the reference's
+ * count; it is the point past which the tail is genuinely a scan rather than
+ * a read, on the rail widths this pair is measured against. The tail is
+ * never hidden: `facetsAllFilters` names how many are in it.
  */
-export const FACET_VISIBLE_GROUPS = 8;
+export const FACET_VISIBLE_GROUPS = 16;
 
 /** What a host's category control is handed. */
 export interface CategoryFilterSlotProps {
@@ -260,17 +266,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 +336,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 +360,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}`,
@@ -470,33 +490,43 @@ function skippedNames(
 
 /**
  * The empty arm of the panel — the ONE place "this search offers no filters"
- * may be said, and the two answers that forbid it (D175).
+ * may be said, and the three things that forbid it (D175, amended).
  *
- * A group list of zero is not the same claim. `withheld` names groups the
- * counter counted and then held back for describing too little of the result
- * set: they exist, so the honest line is how many. `planUnavailable` means
- * the server could not work a plan out at all — the reader hears that from
- * `<DegradationNotice>`, and this arm's only job is to not contradict it.
+ * A group list of zero is not "nothing on the rail". `withheld` names groups
+ * the counter counted and then held back for describing too little of the
+ * result set: they exist, so this is not the search's own claim to make.
+ * `planUnavailable` means the server could not work a plan out at all — the
+ * reader hears that from `<DegradationNotice>`, and this arm's only job is to
+ * not contradict it. `hasOtherDrawable` means the rail is already drawing
+ * something beside the facet groups — a price row, a location constraint, a
+ * partition — and "no filters" would be false the moment any of those is on
+ * screen.
+ *
+ * This USED to be two sentences: `facetsEmpty` for the last case and
+ * `facetsWithheld` — "N filters apply to too few of these results" — for the
+ * first. A reference catalogue checked against the same case says NEITHER:
+ * it leaves the filters visible with low counts and explains nothing. So
+ * `withheld` (and, the same way, `skipped`) now suppress this arm instead of
+ * replacing its text — the arm says nothing, and `data-withheld` is a test
+ * hook a shopper never reads.
  *
  * A COMPONENT rather than a ternary inline in `empty=`, because `LoadList`
  * reads a nullish `empty` as "no arm given" and draws its own default, which
  * is the sentence again. An element that renders `null` says nothing; a
  * `null` prop says it louder.
  */
-function FacetsEmptyArm(props: { readonly bag: FacetPanelBag }): ReactElement | null {
+function FacetsEmptyArm(props: {
+  readonly bag: FacetPanelBag;
+  /** Something else on the rail already makes "no filters" false. */
+  readonly hasOtherDrawable: boolean;
+}): ReactElement | null {
   const t = useT();
-  const tPlural = useTPlural();
   const withheld = props.bag.withheld.length;
-  if (withheld > 0) {
-    return (
-      <EmptyState
-        compact
-        title={tPlural(SEARCH_I18N_KEYS.facetsWithheld, { count: withheld })}
-        testId="facets-withheld"
-      />
-    );
+  if (withheld > 0 || props.bag.planUnavailable || props.hasOtherDrawable) {
+    return withheld > 0 ? (
+      <span hidden data-testid="facets-withheld" data-withheld={withheld} />
+    ) : null;
   }
-  if (props.bag.planUnavailable) return null;
   return (
     <EmptyState compact title={t(SEARCH_I18N_KEYS.facetsEmpty)} testId="facets-empty" />
   );
@@ -513,6 +543,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 } : {})}>
@@ -550,6 +587,16 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
           // classified catalogue means parcel weight and wholesale packing.
           const coreRanges = ranges.filter((group) => group.core);
           const attributeRanges = ranges.filter((group) => !group.core);
+          // Is there anything on this rail besides the facet groups? A price
+          // row, an applied location, or the partition slot all make "this
+          // search offers no filters" false even when the group list itself
+          // is empty. `state.geo` rather than a rendered control: the place
+          // and its radius are drawn by `<LocationSummaryLine>` beside this
+          // panel, not inside it, but the constraint is still on the rail.
+          const hasOtherDrawable =
+            props.partition !== undefined ||
+            coreRanges.length > 0 ||
+            state.geo !== undefined;
           return (
           <Flex vertical gap={spacing[3]} data-testid="search-facets">
             {/* In a 280px rail this row laid the word "Filters" out in a
@@ -577,7 +624,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}
@@ -657,7 +704,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               state={bag.state}
               testId="facets"
               skeletonRows={4}
-              empty={<FacetsEmptyArm bag={bag} />}
+              empty={<FacetsEmptyArm bag={bag} hasOtherDrawable={hasOtherDrawable} />}
               failed={(error) => (
                 <ErrorAlert
                   testId="facets-failed"
@@ -845,10 +892,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,33 @@ 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";
+  /**
+   * How many groups the rail draws before the rest fold behind "All filters"
+   * — see {@link FacetPanelPaneProps.visibleGroups}.
+   *
+   * Defaulted PER LAYOUT, the same reasoning as `dictionaryMode`: 16 in the
+   * desktop COLUMN, where the rail sits on screen the whole time and the tail
+   * is a genuine scroll away; 8 in the phone SHEET, which is already a modal
+   * a person paid a tap to open — folding its tail behind a second control
+   * saves less than folding a column's does. Set it to override either.
+   */
+  readonly visibleGroups?: number | null;
   /** Print the engine's list of uncounted facet slugs in the filter panel.
    * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
   readonly skippedNotice?: boolean;
@@ -422,6 +449,8 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
+  readonly dictionaryMode?: "field" | "inline";
+  readonly visibleGroups?: number | null;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly renderEmptyExits?: () => ReactNode;
   readonly locale?: string;
@@ -516,11 +545,12 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const filtersEmpty =
     facets.state.status === "ready" &&
     facets.state.data.length === 0 &&
-    // Zero groups is not zero filters: `withheld` names groups the server
-    // counted and held back for covering too little of the result set, and
-    // the panel's job is to say how many (D175). Skipping the column would
-    // put that sentence nowhere.
-    facets.withheld.length === 0 &&
+    // `withheld` (groups the server counted and held back for covering too
+    // little of the result set) used to keep the column open so the panel
+    // could name how many. It no longer prints that sentence at all (D175,
+    // amended) — a reference catalogue says nothing in this case either — so
+    // zero groups plus zero of everything else below really is nothing to
+    // show.
     facets.activeFilters === 0 &&
     ranges.length === 0 &&
     state.category === undefined &&
@@ -545,7 +575,22 @@ 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")}
+          // `??` would treat an explicit `null` ("never fold") the same as
+          // "not set": `visibleGroups` uses `null` as a real value, unlike
+          // `dictionaryMode` above, so only `undefined` falls through.
+          visibleGroups={
+            props.visibleGroups !== undefined
+              ? props.visibleGroups
+              : layout === "sheet"
+                ? 8
+                : 16
+          }
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(props.renderEmptyExits !== undefined
             ? { renderEmptyExits: props.renderEmptyExits }
@@ -805,6 +850,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     onViewChange,
     resultsAction,
     resultsHeadingLevel,
+    dictionaryMode,
+    visibleGroups,
     mode,
     ...parseOptions
   } = props;
@@ -814,6 +861,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
       <SearchStateProvider adapter={adapter} geoOffer={geoOffer} {...parseOptions}>
         <SearchPageBody
           {...(renderCard !== undefined ? { renderCard } : {})}
+          {...(dictionaryMode !== undefined ? { dictionaryMode } : {})}
+          {...(visibleGroups !== undefined ? { visibleGroups } : {})}
           {...(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/es.ts

@@ -75,10 +75,6 @@ export const searchI18nBundleEs: I18nDictionary = {
     "Los recuentos son aproximados: había demasiados candidatos para contarlos todos.",
   "search.facets.skipped":
     "Estos filtros no se contaron para esta búsqueda: {slugs}",
-  "search.facets.withheld.one":
-    "{count} filtro se aplica a muy pocos de estos resultados",
-  "search.facets.withheld.other":
-    "{count} filtros se aplican a muy pocos de estos resultados",
   "search.facets.not_counted": "sin contar",
   "search.facets.drill_down_hint":
     "Cada recuento es lo que obtendrías eligiendo ese valor en lugar del actual.",

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/i18n/keys.ts

@@ -111,22 +111,24 @@ export const SEARCH_I18N_KEYS = {
   facetsTitle: "search.facets.title",
   facetsLoading: "search.facets.loading",
   facetsLoadFailed: "search.facets.load_failed",
+  /**
+   * "This search offers no filters" — the ONE sentence the empty arm may
+   * print, and only when the rail draws nothing else either (no price, no
+   * location, no partition — see `FacetsEmptyArm`'s `hasOtherDrawable`).
+   *
+   * D175, amended: this used to be one of TWO sentences, the other keyed on
+   * `facet_meta.withheld` ("N filters apply to too few of these results").
+   * A reference catalogue was checked for the same case and says neither —
+   * it leaves the filters visible with low counts and no explanation of why
+   * some are thin. `withheld` (and `skipped`) now suppress this sentence
+   * instead of replacing it; a test that needs the count reads
+   * `data-withheld` on the empty arm, which carries no text.
+   */
   facetsEmpty: "search.facets.empty",
   facetsClear: "search.facets.clear",
   facetsClearAll: "search.facets.clear_all",
   facetsApproximate: "search.facets.approximate",
   facetsSkipped: "search.facets.skipped",
-  /**
-   * "N filters apply to too few of these results" — the sentence that
-   * REPLACES {@link facetsEmpty} whenever `facet_meta.withheld` is not
-   * empty. A PLURAL FAMILY: it counts a noun in words.
-   *
-   * D175: a branch category holding 46 phones that all carry a manufacturer
-   * printed "this search offers no filters". The groups were counted and
-   * then withheld for covering too little of the set — so "there are none"
-   * was false, and the honest sentence is this one, with the number in it.
-   */
-  facetsWithheld: "search.facets.withheld",
   /** Shown INSTEAD of a count for a slug the server did not count. */
   facetsNotCounted: "search.facets.not_counted",
   facetsDrillDownHint: "search.facets.drill_down_hint",
@@ -471,7 +473,6 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.filtersShowCountAtLeast,
   SEARCH_I18N_KEYS.boxCategoryCount,
   SEARCH_I18N_KEYS.facetsMatchCount,
-  SEARCH_I18N_KEYS.facetsWithheld,
 ];
 
 /**
@@ -544,10 +545,6 @@ export const searchI18nBundleEn: Record<string, string> = {
     "Counts are approximate — there were too many candidates to count them all.",
   "search.facets.skipped":
     "These filters were not counted for this search: {slugs}",
-  "search.facets.withheld.one":
-    "{count} filter applies to too few of these results",
-  "search.facets.withheld.other":
-    "{count} filters apply to too few of these results",
   "search.facets.not_counted": "not counted",
   "search.facets.drill_down_hint":
     "Each count is what you would get by choosing that value instead of the one you have.",

package/src/i18n/ru.ts

@@ -100,14 +100,6 @@ export const searchI18nBundleRu: I18nDictionary = {
     "Счётчики приблизительные — подходящих объявлений слишком много, чтобы пересчитать все.",
   "search.facets.skipped":
     "Эти фильтры для текущего поиска не посчитаны: {slugs}",
-  "search.facets.withheld.one":
-    "Ещё {count} фильтр подходит слишком малой части результатов",
-  "search.facets.withheld.few":
-    "Ещё {count} фильтра подходят слишком малой части результатов",
-  "search.facets.withheld.many":
-    "Ещё {count} фильтров подходят слишком малой части результатов",
-  "search.facets.withheld.other":
-    "Ещё {count} фильтра подходят слишком малой части результатов",
   "search.facets.not_counted": "не посчитано",
   "search.facets.drill_down_hint":
     "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",

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,