@stapel/search-react 0.27.0 → 0.29.0

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.27.0",
+  "version": "0.29.0",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.14 <0.15"
@@ -811,9 +811,12 @@
     "search.facets.approximate",
     "search.facets.clear",
     "search.facets.clear_all",
+    "search.facets.dictionary_all_values",
     "search.facets.dictionary_any",
     "search.facets.dictionary_chosen",
+    "search.facets.dictionary_done",
     "search.facets.dictionary_empty",
+    "search.facets.dictionary_recommended",
     "search.facets.dictionary_search",
     "search.facets.drill_down_hint",
     "search.facets.empty",
@@ -941,6 +944,7 @@
   ],
   "exports": {
     "runtime": [
+      "DEFAULT_HISTORY_MODE",
       "EMPTY_FACET_KEYS",
       "FACETABLE_FEATURE_TYPES",
       "FACET_PLAN_EVIDENCE",
@@ -1055,6 +1059,7 @@
       "FacetPanelBag",
       "FacetSelection",
       "FacetWithheldGroup",
+      "HistoryMode",
       "OtherCategoriesBag",
       "OtherCategoryRow",
       "ParseSearchStateOptions",
@@ -1078,6 +1083,7 @@
       "SearchGeo",
       "SearchGeoBox",
       "SearchGeoCenter",
+      "SearchHistoryKind",
       "SearchI18nKey",
       "SearchImageResolver",
       "SearchItem",
@@ -1100,7 +1106,8 @@
       "SuggestParams",
       "SuggestResponse",
       "UseSearchBoxOptions",
-      "UseSearchCountOptions"
+      "UseSearchCountOptions",
+      "WriteSearchStateDefaults"
     ]
   }
 }

package/nav-manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -52,14 +52,14 @@
   ],
   "size-limit": [
     {
-      "name": "index — the headless pair (client + hooks + URL codec + facet model incl. the facetability rule, the label-source order, the across-alphabets prefix matcher, the SCHEMA-order comparator that puts a category's required axes first and the bounded-integer picker list): no antd, no react-router. Raised 12 → 12.5 KB for the rail-order comparator, the shared drawability predicate (one rule for the rail and the chip row) and the picker bounds. Raised 12.5 → 13 KB for `useOtherCategories`, which reads the sections an answer is made of out of `facet_meta.categories` — the read that replaced a storefront's second request, then 13 → 13.5 KB for the SHORT FEATURE KEYS: the two-direction `url_key` map (built with the server's own collision rules, so an ambiguous short form keeps the slug on both sides), its publication seam from the answer up to the state provider, and the vocabulary-backed predicate the drawability rule and the dictionary shape now share",
+      "name": "index — the headless pair (client + hooks + URL codec + facet model incl. the facetability rule, the label-source order, the across-alphabets prefix matcher, the SCHEMA-order comparator that puts a category's required axes first and the bounded-integer picker list): no antd, no react-router. Raised 12 → 12.5 KB for the rail-order comparator, the shared drawability predicate (one rule for the rail and the chip row) and the picker bounds. Raised 12.5 → 13 KB for `useOtherCategories`, which reads the sections an answer is made of out of `facet_meta.categories` — the read that replaced a storefront's second request, then 13 → 13.5 KB for the SHORT FEATURE KEYS: the two-direction `url_key` map (built with the server's own collision rules, so an ambiguous short form keeps the slug on both sides), its publication seam from the answer up to the state provider, and the vocabulary-backed predicate the drawability rule and the dictionary shape now share, then 13.5 → 13.75 KB for the documented history policy (`DEFAULT_HISTORY_MODE`, one push/replace table every mutator follows instead of an ad hoc boolean per call) and the codec omitting `type`/`sort`/`limit` from the address when they equal the default a host declared",
       "path": "dist/index.js",
-      "limit": "13.5 KB"
+      "limit": "13.75 KB"
     },
     {
-      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes",
       "path": "dist/default/index.js",
-      "limit": "27.75 KB"
+      "limit": "29.25 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -67,9 +67,9 @@
       "limit": "1 KB"
     },
     {
-      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
+      "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry. Raised 4.75 → 5 KB for the dictionary sheet's three headings",
       "path": "dist/i18n/ru.js",
-      "limit": "4.75 KB"
+      "limit": "5 KB"
     },
     {
       "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry. Raised 3.5 → 3.75 KB for the three strings of the other-categories line",
@@ -81,7 +81,7 @@
     "@stapel/attributes-react": ">=0.4.0",
     "@stapel/core": ">=0.18.1 <1.0.0",
     "@stapel/image": ">=0.3.0",
-    "@stapel/tokens-antd": ">=0.11.0",
+    "@stapel/tokens-antd": ">=0.12.0",
     "@tanstack/react-query": "^5.0.0",
     "antd": ">=5.20.0 <7",
     "react": ">=19",
@@ -116,11 +116,11 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@stapel/core": "^0.25.1",
-    "@stapel/attributes-react": "^0.16.0",
-    "@stapel/showcase": "^0.3.0",
     "@stapel/image": "^0.4.2",
     "@stapel/tokens": "^0.7.0",
-    "@stapel/tokens-antd": "^0.17.0"
+    "@stapel/attributes-react": "^0.16.0",
+    "@stapel/tokens-antd": "^0.17.0",
+    "@stapel/showcase": "^0.3.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

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

package/src/default/FacetGroupControl.tsx

@@ -62,10 +62,12 @@
  * them visible as before: folding everything would leave a heading over
  * nothing. Chosen options are always visible, wherever their count went.
  */
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
+import { SkinPickerSheet } from "@stapel/tokens-antd/skin";
+import type { PickerGroup, PickerOption } from "@stapel/tokens-antd/skin";
 import { controls, cssVar, radii, spacing } from "@stapel/tokens";
 import { featureConfig, featureType } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
@@ -632,6 +634,246 @@ function DictionaryField(props: {
   );
 }
 
+/**
+ * How many values the sheet's «All values» band adds per page.
+ *
+ * Fifty is the vocabulary endpoint's own page size, and it is the number past
+ * which a phone list stops being scrolled and starts being searched. Reaching
+ * the end of the list asks for the next fifty, so a 418-make level is a
+ * scroll rather than 418 mounted rows.
+ */
+export const FACET_SHEET_PAGE = 50;
+
+/** One facet option as the shared picker reads it. The count rides along as
+ * the row's second line: a filter without its remaining count is the
+ * drill-down facet turned naive, and that rule does not stop at a sheet. */
+function pickerRow(option: FacetOption, notCounted: string): PickerOption {
+  return {
+    value: option.value,
+    label: option.label,
+    description: option.count === null ? notCounted : String(option.count),
+  };
+}
+
+/**
+ * A dictionary group on a PHONE: a trigger row, and a nested sheet.
+ *
+ * ── What the buyer was looking at ─────────────────────────────────────────
+ *
+ * The composer's own vocabulary picker (`@stapel/attributes-react`'s
+ * `ref_select` editor) is a trigger that opens a sheet with a search box, a
+ * recommended band and the rest — zero checkboxes. The buyer's filter sheet
+ * drew the SAME axis as a wall of eight checkboxes with a "Find a value" box
+ * and a "Show all (38)" under it, and no way to say "any". Two halves of one
+ * product teaching two different gestures for one dictionary is the defect;
+ * this mode is the half that moved.
+ *
+ * ── Why the shared `SkinPickerSheet` and not a local one ──────────────────
+ *
+ * It is the same component the composer's picker draws: the search box pinned
+ * above the list, the checkmarks, the commit button above the home indicator,
+ * the swipe/Esc/back dismissal, the skeleton and the empty arm. A pair that
+ * re-derives that gets a near-miss of it, which is exactly how the two halves
+ * drifted the first time.
+ *
+ * ── The two bands ─────────────────────────────────────────────────────────
+ *
+ * «Recommended» is the busiest values BY COUNT — the answer's own evidence,
+ * capped at {@link FACET_VISIBLE_OPTIONS} — with the chosen values in front
+ * of it, because a filter a person cannot see is a filter they cannot remove.
+ * «All values» is everything else, alphabetically, a page at a time. Once
+ * something is typed the bands collapse into one: a "Recommended" heading
+ * over rows that do not answer the box is the stale-list defect wearing a
+ * hat.
+ *
+ * The box filters LOCALLY and across alphabets (`translitPrefixMatch`, the
+ * same matcher the desktop field uses), so a Cyrillic spelling of a Latin
+ * make finds it. Nothing here touches the URL: what a person typed to FIND a
+ * filter is not part of the search they would share. The COMMIT does — the
+ * whole draft is written to the slug's URL key at once.
+ */
+function DictionarySheet(props: {
+  readonly group: FacetGroup;
+  readonly onSetValues: (slug: string, values: readonly string[]) => void;
+}): ReactElement {
+  const t = useT();
+  const { group } = props;
+  const [open, setOpen] = useState(false);
+  const [needle, setNeedle] = useState("");
+  const [page, setPage] = useState(FACET_SHEET_PAGE);
+
+  const chosen = group.options.filter((option) => option.selected);
+  const query = needle.trim();
+
+  const { groups, total } = useMemo(() => {
+    const notCounted = t(SEARCH_I18N_KEYS.facetsNotCounted);
+    const hit = (option: FacetOption): boolean =>
+      query === "" ||
+      translitPrefixMatch(query, option.label) ||
+      translitPrefixMatch(query, option.value);
+    const selected = group.options.filter((option) => option.selected);
+    const byCount = [...group.options].sort(
+      (a, b) => (b.count ?? 0) - (a.count ?? 0)
+    );
+
+    if (query !== "") {
+      // One band while the box holds something: the chosen values first (they
+      // are the ones with an off-switch to reach), then the evidence order.
+      const hits = [
+        ...selected.filter(hit),
+        ...byCount.filter((option) => !option.selected && hit(option)),
+      ];
+      return {
+        total: hits.length,
+        groups: [
+          {
+            key: "all",
+            label: t(SEARCH_I18N_KEYS.facetsDictionaryAllValues),
+            options: hits.slice(0, page).map((o) => pickerRow(o, notCounted)),
+          },
+        ] as readonly PickerGroup[],
+      };
+    }
+
+    // The band never drops a chosen value, however cold it is: its cap grows
+    // to hold them rather than pushing one of them into the alphabet.
+    const cap = Math.max(FACET_VISIBLE_OPTIONS, selected.length);
+    const band: FacetOption[] = [];
+    const banded = new Set<string>();
+    for (const option of [...selected, ...byCount]) {
+      if (banded.has(option.value) || band.length >= cap) continue;
+      band.push(option);
+      banded.add(option.value);
+    }
+    const rest = group.options
+      .filter((option) => !banded.has(option.value))
+      .sort((a, b) => a.label.localeCompare(b.label));
+    return {
+      total: band.length + Math.min(rest.length, page),
+      groups: [
+        {
+          key: "band",
+          label: t(SEARCH_I18N_KEYS.facetsDictionaryRecommended),
+          options: band.map((o) => pickerRow(o, notCounted)),
+        },
+        {
+          key: "all",
+          label: t(SEARCH_I18N_KEYS.facetsDictionaryAllValues),
+          options: rest.slice(0, page).map((o) => pickerRow(o, notCounted)),
+        },
+      ] as readonly PickerGroup[],
+    };
+  }, [group, query, page, t]);
+
+  // How many rows exist behind the current page — what "there is more" means.
+  const available = group.options.length;
+
+  const text =
+    chosen.length > 0
+      ? chosen.map((option) => option.label).join(", ")
+      : t(SEARCH_I18N_KEYS.facetsDictionaryAny);
+
+  return (
+    <>
+      <button
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={group.label}
+        style={DICTIONARY_FIELD}
+        data-testid={`facet-dictionary-trigger-${group.slug}`}
+        data-chosen={chosen.length}
+        data-analytics="none"
+        data-analytics-reason="opening a filter group is a read, not a flow step"
+        onClick={() => {
+          setOpen(true);
+        }}
+      >
+        <span style={DICTIONARY_FIELD_TEXT}>{text}</span>
+        {chosen.length > 0 && (
+          <Typography.Text
+            type="secondary"
+            data-testid={`facet-dictionary-trigger-count-${group.slug}`}
+          >
+            {chosen.length}
+          </Typography.Text>
+        )}
+        <ChevronGlyph open={open} />
+      </button>
+      <SkinPickerSheet
+        mode="multi"
+        open={open}
+        onClose={() => {
+          setOpen(false);
+          setNeedle("");
+          setPage(FACET_SHEET_PAGE);
+        }}
+        title={group.label}
+        testId={`facet-dictionary-sheet-${group.slug}`}
+        doneLabel={t(SEARCH_I18N_KEYS.facetsDictionaryDone)}
+        searchPlaceholder={t(SEARCH_I18N_KEYS.facetsDictionarySearch)}
+        emptyLabel={t(SEARCH_I18N_KEYS.facetsDictionaryEmpty)}
+        // The caller owns the filtering — the sheet's own local filter matches
+        // on the label only, and this axis is searched across alphabets.
+        searchValue={needle}
+        onSearchChange={(next) => {
+          setNeedle(next);
+          setPage(FACET_SHEET_PAGE);
+        }}
+        groups={groups}
+        // Everything handed over is drawn: the paging above is this
+        // component's, so the sheet's own row cap must not fold it again.
+        maxRows={Math.max(1, total)}
+        onEndReached={() => {
+          setPage((current) =>
+            current >= available ? current : current + FACET_SHEET_PAGE
+          );
+        }}
+        values={group.selected}
+        onChange={(values) => {
+          props.onSetValues(group.slug, values);
+        }}
+      />
+    </>
+  );
+}
+
+/**
+ * The three faces of one dictionary, chosen by mode.
+ *
+ * `"sheet"` without a bulk setter falls back to the FIELD rather than to the
+ * inline wall: a trigger that opens a list is the shape both surfaces are
+ * moving to, and the wall is the thing the pass named.
+ */
+function DictionaryControl(props: {
+  readonly group: FacetGroup;
+  readonly mode: "field" | "inline" | "sheet" | undefined;
+  readonly onToggle: (slug: string, value: string) => void;
+  readonly onSetValues?: (slug: string, values: readonly string[]) => void;
+  readonly visible: number;
+}): ReactElement {
+  const { onSetValues } = props;
+  if (props.mode === "sheet" && onSetValues !== undefined) {
+    return <DictionarySheet group={props.group} onSetValues={onSetValues} />;
+  }
+  if (props.mode === "field" || props.mode === "sheet") {
+    return (
+      <DictionaryField
+        group={props.group}
+        onToggle={props.onToggle}
+        visible={props.visible}
+      />
+    );
+  }
+  return (
+    <DictionaryBody
+      group={props.group}
+      onToggle={props.onToggle}
+      visible={props.visible}
+    />
+  );
+}
+
 export interface FacetGroupControlProps {
   readonly group: FacetGroup;
   readonly onToggle: (slug: string, value: string) => void;
@@ -652,13 +894,31 @@ export interface FacetGroupControlProps {
    * value only — the person owns the state after the first click. */
   readonly defaultOpen?: boolean;
   /**
-   * How a `"dictionary"` group is drawn. `"field"` is the desktop shape — a
-   * select-style field reading its chosen values or "Any", which opens the
-   * searchable list; `"inline"` (the default) keeps the list open, the shape
-   * a phone sheet wants because the sheet is already the disclosure.
-   * Meaningless for the other three shapes.
+   * How a `"dictionary"` group is drawn. Meaningless for the other three
+   * shapes.
+   *
+   *  - `"field"` — the desktop shape: a select-style field reading its chosen
+   *    values or "Any", which opens the searchable list under it;
+   *  - `"sheet"` — the PHONE shape: a trigger row reading the same sentence,
+   *    opening a nested picker sheet with a search box, a recommended band
+   *    and the rest. The same control the composer's vocabulary picker is, so
+   *    one dictionary is one gesture on both halves of the product. Needs
+   *    {@link FacetGroupControlProps.onSetValues} — the sheet commits a whole
+   *    draft at once, and a per-value toggle cannot apply one; without it the
+   *    group falls back to `"field"`;
+   *  - `"inline"` (the default) keeps the list open — a group that is already
+   *    the only thing on its surface, such as a per-chip sheet.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
+  /**
+   * Write a slug's chosen values in ONE go — `useFacetPanel`'s `setValues`.
+   *
+   * `onToggle` reads the current state to flip one value, so N toggles in one
+   * tick collapse into the last one; a sheet that commits a draft of several
+   * ticks needs the bulk write. Optional so no existing host changes, and
+   * only `dictionaryMode: "sheet"` reads it.
+   */
+  readonly onSetValues?: (slug: string, values: readonly string[]) => void;
 }
 
 export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
@@ -739,21 +999,17 @@ export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
       {/* Closed means NOT RENDERED, not hidden: a hundred `display:none`
           checkboxes are still a hundred stops for a screen reader, and the
           measured rail held 118 of them. */}
-      {open &&
-        shape === "dictionary" &&
-        (props.dictionaryMode === "field" ? (
-          <DictionaryField
-            group={group}
-            onToggle={props.onToggle}
-            visible={limit ?? FACET_VISIBLE_OPTIONS}
-          />
-        ) : (
-          <DictionaryBody
-            group={group}
-            onToggle={props.onToggle}
-            visible={limit ?? FACET_VISIBLE_OPTIONS}
-          />
-        ))}
+      {open && shape === "dictionary" && (
+        <DictionaryControl
+          group={group}
+          mode={props.dictionaryMode}
+          onToggle={props.onToggle}
+          {...(props.onSetValues !== undefined
+            ? { onSetValues: props.onSetValues }
+            : {})}
+          visible={limit ?? FACET_VISIBLE_OPTIONS}
+        />
+      )}
 
       {open && shape !== "dictionary" && (
         <>

package/src/default/FacetPanelPane.tsx

@@ -315,10 +315,12 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
   /**
    * How a DICTIONARY group is drawn. `"field"` is the desktop shape — a
    * select-style field reading its chosen values or "Any", which opens the
-   * searchable list; `"inline"` (the default) keeps the list open, which is
-   * the phone sheet's shape because a sheet is already a disclosure.
+   * searchable list under it; `"sheet"` is the phone's — the same trigger
+   * row, opening a nested picker sheet with a search box, a recommended band
+   * and the rest, which is the control the composer's vocabulary picker
+   * already is; `"inline"` (the default) keeps the list open.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
 }
 
 /**
@@ -828,6 +830,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                         key={needle === "" ? group.slug : `${group.slug}:match`}
                         group={group}
                         onToggle={bag.toggle}
+                        onSetValues={bag.setValues}
                         collapsible
                         defaultOpen={
                           needle !== "" ||

package/src/default/OtherCategoriesLine.tsx

@@ -30,9 +30,18 @@
  * show a different, larger number, so the caption would be a lie one click
  * later. Each entry therefore writes the `category` parameter of the search
  * already on screen, keeping the query: press "Cars 12" and twelve results
- * follow. That is a state change, so each entry is a real `<button>` and not
- * an anchor.
+ * follow.
  *
+ * Without {@link OtherCategoriesLineProps.categoryHref} that state change is
+ * ALL an entry does, so it is a plain `<button>` with no `href` — no address
+ * to hover, no "open in a new tab", nothing a crawler can follow. `categoryHref`
+ * turns the entry into a real `<a href>` without giving up the in-app
+ * narrowing: a plain click still rewrites the query in place (a full
+ * navigation would answer a different question than the one the count was
+ * counted for), while a modified click — the browser's own "open in a new
+ * tab/window" — is left alone and follows the address like any other link.
+ *
+
  * ## Two rows on a phone, at most
  *
  * The cap is halved on the sheet surface ({@link OTHER_CATEGORIES_PHONE_LIMIT}),
@@ -70,6 +79,10 @@ export const OTHER_CATEGORIES_SLOT_MIN_HEIGHT = 24;
  * drops the row rather than printing a number at a person. */
 export type OtherCategoryNamer = (category: string) => string | undefined;
 
+/** Resolves an id path to a real, navigable address. Returning `undefined`
+ * leaves the row's in-app narrowing as the only way to press it. */
+export type OtherCategoryHrefResolver = (category: string) => string | undefined;
+
 export interface OtherCategoriesLineProps {
   /** How many entries before the fold (default {@link OTHER_CATEGORIES_LIMIT}). */
   readonly limit?: number;
@@ -86,6 +99,24 @@ export interface OtherCategoriesLineProps {
    * slug — and drops the rest, because "163 · 149" is not a sentence.
    */
   readonly categoryName?: OtherCategoryNamer;
+  /**
+   * A real address for a category id path, when the host has one — a
+   * category page's own URL, most usefully.
+   *
+   * Without it every entry is a `<button>` with no `href`: it narrows the
+   * search on click, and nothing else — no "open in a new tab", no address
+   * to hover, nothing a crawler can follow. With it the entry becomes a real
+   * `<a href>` (a middle-click, a ctrl/cmd-click, "open in new tab" all work
+   * as they do for any link), while a plain click still narrows THIS search
+   * in place rather than leaving it — the whole reason the count beside a
+   * name is trustworthy is that it is a count for the query on screen, and a
+   * full navigation to the host's address would be answering a different
+   * question than the one the click asked.
+   *
+   * A row this returns nothing for keeps the in-app-only behaviour; the row
+   * is dropped only when it has no NAME, exactly as without this prop.
+   */
+  readonly categoryHref?: OtherCategoryHrefResolver;
   /** Skip the read entirely — mirrors `<SearchResultsPane enabled>`. */
   readonly enabled?: boolean;
 }
@@ -130,6 +161,7 @@ export function otherCategoriesCss(): string {
 interface Entry {
   readonly row: OtherCategoryRow;
   readonly name: string;
+  readonly href?: string;
 }
 
 export function OtherCategoriesLine(
@@ -152,7 +184,9 @@ export function OtherCategoriesLine(
   for (const row of bag.rows) {
     const name =
       props.categoryName?.(row.category) ?? row.name ?? otherCategoryLeaf(row.category);
-    if (name !== undefined) entries.push({ row, name });
+    if (name === undefined) continue;
+    const href = props.categoryHref?.(row.category);
+    entries.push(href !== undefined ? { row, name, href } : { row, name });
   }
 
   const shown = expanded ? entries : entries.slice(0, limit);
@@ -201,12 +235,26 @@ export function OtherCategoriesLine(
             style={ENTRY}
             data-testid="search-other-category"
             data-category={entry.row.category}
+            {...(entry.href !== undefined ? { href: entry.href } : {})}
             data-analytics="none"
             data-analytics-reason="narrowing a search is a read, not a flow step"
             aria-label={t(SEARCH_I18N_KEYS.otherCategoriesNarrow, {
               name: entry.name,
             })}
-            onClick={() => {
+            onClick={(event) => {
+              // A real `href` still narrows THIS search in place on a plain
+              // click — a full navigation would answer a different query
+              // than the one the count beside the name was counted for.
+              // Anything asking for a new tab/window (a modified click) is
+              // left to the browser, which is what makes the address real
+              // rather than decorative.
+              if (
+                entry.href !== undefined &&
+                (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+              ) {
+                return;
+              }
+              event.preventDefault();
               setCategory(entry.row.category);
             }}
           >