@stapel/search-react 0.24.0 → 0.26.0

package/src/headless/useOtherCategories.ts

@@ -0,0 +1,193 @@
+/**
+ * "The same query, in another section" — the categories THIS answer is made
+ * of, read out of the answer that drew the cards.
+ *
+ * ## What it replaces
+ *
+ * A storefront drew this as a full-width block under the results: one row per
+ * category, fetched from `/suggest` AFTER the page had settled, so a tall
+ * panel appeared a beat late and pushed everything a person was already
+ * reading. Both halves were avoidable. The block was tall where one line
+ * says the same thing, and the request was a second ask for something the
+ * page already had: `/query` answers with `facet_meta.categories` — `{path,
+ * count}` for every category the candidate set contains — and that is
+ * exactly the list the block was printing.
+ *
+ * So the rows come from the SEARCH response. No request of this hook's own
+ * while there are results, and therefore nothing to arrive late.
+ *
+ * ## The one case that DOES earn a request
+ *
+ * An empty result set has no candidates, so `facet_meta.categories` is empty
+ * too — and that is precisely the screen where "this word exists in these
+ * sections" is worth the most. There, and only there, `/suggest` is asked.
+ * The bag says so through {@link OtherCategoriesBag.reserving}, so a surface
+ * can hold the row's height from the first frame instead of letting the
+ * answer push the page a second time.
+ *
+ * ## Names come from the cache, not from a request
+ *
+ * `facet_meta.categories` carries id PATHS and counts, never names — the
+ * catalogue belongs to `categories-react`. Three sources are tried, in order:
+ *
+ *  1. the host's resolver (a surface prop), which is the only one that can
+ *     name an id path with certainty;
+ *  2. the `/suggest` answer ALREADY IN THE QUERY CACHE — the type-ahead asked
+ *     about this same word a keystroke earlier, and its rows carry the
+ *     server's own names. `useSuggest` with `enabled: false` hands back a
+ *     cached answer and fires nothing, so this costs no request;
+ *  3. the path's last segment, when it is a slug rather than a number.
+ *
+ * A row none of the three can name is DROPPED rather than printed as "163" —
+ * the same rule `categoryLeaf` states for the category chip.
+ */
+import type { SearchResponse, SuggestCategory } from "../api/types.js";
+import { useSearchQuery, useSuggest } from "../model/queries.js";
+import { offerableCategories } from "./useSearchBox.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+/** How many entries the line prints before it folds the rest. */
+export const OTHER_CATEGORIES_LIMIT = 8;
+
+/**
+ * The phone's cap.
+ *
+ * Half the desktop's, because the requirement is a LINE and at 390px eight
+ * entries are not one — they are the block this replaces, wearing a comma.
+ * Four short section names plus the fold marker are the two rows a phone can
+ * spend on a navigation aid above a list of cards.
+ */
+export const OTHER_CATEGORIES_PHONE_LIMIT = 4;
+
+/** One category the current answer reached, with the count that answer gives it. */
+export interface OtherCategoryRow {
+  /** The slash-joined id path — the same string the `category` filter takes,
+   * so narrowing to it needs no translation and no tree. */
+  readonly category: string;
+  /** Documents matching THIS query that live there. Scoped to the query, which
+   * is why narrowing the search is the honest destination and the bare
+   * category feed is not: the feed would show a different number. */
+  readonly count: number;
+  /** The server's own name, when this row came from `/suggest` or when a
+   * cached suggest answer named the same path. */
+  readonly name?: string;
+  /** Display names root→leaf, when the server sent them. */
+  readonly path?: readonly string[];
+}
+
+export interface OtherCategoriesBag {
+  /** Every row, uncapped and in the order the line should print them. Capping
+   * is a decision about the SURFACE (a phone takes fewer), so it is not made
+   * here. */
+  readonly rows: readonly OtherCategoryRow[];
+  /**
+   * Where the rows came from. `"results"` — the search response itself, drawn
+   * in the same frame as the cards. `"suggest"` — the empty-result path, the
+   * only one with a request behind it. `"none"` — nothing to offer.
+   */
+  readonly source: "results" | "suggest" | "none";
+  /**
+   * The empty-result path is active, so a row is coming from a request that
+   * has not landed (or landed empty). A surface keeps the height either way:
+   * space reserved from the first frame is space nothing can push.
+   */
+  readonly reserving: boolean;
+  /** That request is in flight right now. */
+  readonly pending: boolean;
+}
+
+const NO_ROWS: readonly OtherCategoryRow[] = [];
+
+/** The path's last segment, when it names something — never a bare id. */
+export function otherCategoryLeaf(category: string): string | undefined {
+  const parts = category.split("/").filter((part) => part.length > 0);
+  const leaf = parts[parts.length - 1];
+  if (leaf === undefined || /^\d+$/.test(leaf)) return undefined;
+  return leaf;
+}
+
+/** The rows the ANSWER carries, busiest first and without the section the
+ * search is already in. */
+function rowsFromResponse(
+  answer: SearchResponse | undefined,
+  applied: string | undefined,
+  named: ReadonlyMap<string, SuggestCategory>
+): readonly OtherCategoryRow[] {
+  const meta = answer?.facet_meta.categories ?? [];
+  const rows = meta
+    // "Other" than the one the search is in. Descendants stay: narrowing from
+    // a branch to one of its leaves is a different section and the move this
+    // line exists for.
+    .filter((row) => row.category !== applied)
+    .map((row) => {
+      const match = named.get(row.category);
+      return {
+        category: row.category,
+        count: row.count,
+        ...(match !== undefined ? { name: match.name, path: match.path } : {}),
+      };
+    });
+  // The server documents "busiest first" and the cap has to take the busiest
+  // eight; asserting the order here is cheaper than trusting it and being
+  // wrong about which eight a person sees.
+  return [...rows].sort((a, b) =>
+    b.count === a.count ? a.category.localeCompare(b.category) : b.count - a.count
+  );
+}
+
+export function useOtherCategories(
+  options: { readonly enabled?: boolean } = {}
+): OtherCategoriesBag {
+  const { state } = useSearchState();
+  const enabled = options.enabled ?? true;
+
+  // The SAME query the results pane runs: identical key, identical cache
+  // entry, no second request. This hook can therefore be mounted anywhere
+  // under the provider without the envelope having to be threaded to it.
+  const query = useSearchQuery(state, { enabled });
+  const answer = query.data;
+
+  // Ready AND empty. `answer === undefined` is "still loading", which is not
+  // an empty result and must not spend a request.
+  const resultsEmpty = enabled && answer !== undefined && answer.items.length === 0;
+
+  // `enabled: false` still returns whatever the box already put in the cache
+  // and asks nothing — which is how a page WITH results gets the server's
+  // names for free. A page WITHOUT results turns the same hook into the one
+  // request this feature ever makes.
+  const suggest = useSuggest({ type: state.type, q: state.q, enabled: resultsEmpty });
+  // Through the pair's own reader, which is where "this server sent no
+  // categories key at all" is already distinguished from "nothing matched".
+  const suggested = offerableCategories(suggest.data);
+  const named = new Map(suggested.map((row) => [row.category, row]));
+
+  const fromResults = rowsFromResponse(answer, state.category, named);
+
+  const pending = resultsEmpty && suggest.isLoading && suggest.fetchStatus === "fetching";
+
+  if (fromResults.length > 0) {
+    return { rows: fromResults, source: "results", reserving: false, pending: false };
+  }
+
+  if (resultsEmpty) {
+    // The server's rank order is kept as sent: `/suggest` ranks by match grade
+    // and stock before count, and re-sorting by count here would throw that
+    // away for a number that is not what ranked them.
+    const rows = suggested
+      .filter((row) => row.category !== state.category)
+      .map((row) => ({
+        category: row.category,
+        count: row.count,
+        name: row.name,
+        path: row.path,
+      }));
+    return {
+      rows,
+      source: rows.length > 0 ? "suggest" : "none",
+      reserving: true,
+      pending,
+    };
+  }
+
+  return { rows: NO_ROWS, source: "none", reserving: false, pending: false };
+}

package/src/i18n/es.ts

@@ -131,6 +131,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.empty.widen_radius": "Buscar en un radio de {km} km",
   "search.empty.anywhere": "Buscar en todas partes",
   "search.empty.drop_filter": "Sin «{name}»",
+
+  "search.other_categories.label": "Buscar en otras categorías:",
+  "search.other_categories.narrow": "Buscar en {name}",
+  "search.other_categories.more": "{count} más",
   "search.category.title": "Categoría",
   "search.category.clear": "Buscar en todo el catálogo",
   "search.category.current": "Buscando dentro de {path}",

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

@@ -282,6 +282,33 @@ export const SEARCH_I18N_KEYS = {
   /** "Without {name}" — one applied filter, named as its own chip names it. */
   emptyDropFilter: "search.empty.drop_filter",
 
+  // ── the same query, in another section (one line, from the answer) ───────
+  /**
+   * The line's lead-in — "Search in other categories:". It ends in a colon
+   * because what follows is a list on the same line, and a translator who is
+   * shown the string without one has no way to know that.
+   *
+   * Not `search.box.categories` ("Sections", the type-ahead's group heading):
+   * that one titles a menu of destinations while a person types, this one
+   * introduces a row of narrowings beside a result list. Same noun, two
+   * surfaces, and the languages that decline it need both.
+   */
+  otherCategoriesLabel: "search.other_categories.label",
+  /**
+   * The accessible name of one entry. The visible caption is "Cars 12" — a
+   * name and a number, which says nothing about what pressing it DOES. This
+   * does: it narrows the search that is already on screen, and it keeps the
+   * query, which is why the number beside it stays true afterwards.
+   */
+  otherCategoriesNarrow: "search.other_categories.narrow",
+  /**
+   * The fold at the end of the line: how many sections it did not print.
+   * `{count}` is a bare number after a word, not a counted noun in a
+   * sentence, so this is not a plural family — the same shape as
+   * `facetsAllFilters` and `filtersChipOverflow`.
+   */
+  otherCategoriesMore: "search.other_categories.more",
+
   // ── category (a host slot, plus the control that removes it) ─────────────
   categoryTitle: "search.category.title",
   categoryClear: "search.category.clear",
@@ -573,6 +600,11 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.empty.widen_radius": "Search within {km} km",
   "search.empty.anywhere": "Search anywhere",
   "search.empty.drop_filter": "Without {name}",
+
+  "search.other_categories.label": "Search in other categories:",
+  "search.other_categories.narrow": "Search in {name}",
+  "search.other_categories.more": "{count} more",
+
   "search.category.title": "Category",
   "search.category.clear": "Search the whole catalogue",
   "search.category.current": "Searching inside {path}",

package/src/i18n/ru.ts

@@ -166,6 +166,11 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.empty.widen_radius": "Искать в радиусе {km} км",
   "search.empty.anywhere": "Искать везде",
   "search.empty.drop_filter": "Без «{name}»",
+
+  // One line, out of the same answer the cards came from: section and count.
+  "search.other_categories.label": "Поиск в других категориях:",
+  "search.other_categories.narrow": "Искать в разделе «{name}»",
+  "search.other_categories.more": "ещё {count}",
   "search.category.title": "Категория",
   "search.category.clear": "Искать по всему каталогу",
   "search.category.current": "Ищем внутри {path}",

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,
@@ -194,6 +206,16 @@ export type {
 } from "./headless/useFacetLabels.js";
 export { useAppliedSort } from "./headless/useAppliedSort.js";
 export { offerableCategories, useSearchBox } from "./headless/useSearchBox.js";
+export {
+  OTHER_CATEGORIES_LIMIT,
+  OTHER_CATEGORIES_PHONE_LIMIT,
+  otherCategoryLeaf,
+  useOtherCategories,
+} from "./headless/useOtherCategories.js";
+export type {
+  OtherCategoriesBag,
+  OtherCategoryRow,
+} from "./headless/useOtherCategories.js";
 export type { SearchBoxBag, UseSearchBoxOptions } from "./headless/useSearchBox.js";
 export { countQueryState, useSearchCount } from "./headless/useSearchCount.js";
 export type {

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;
 }
 
 /**