@stapel/search-react 0.21.0 → 0.23.0

package/dist/state/translit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Matching a typed prefix against a dictionary value ACROSS ALPHABETS.
+ *
+ * A vocabulary of car makes holds `Toyota`, `Land Rover`, `Timberland` — Latin
+ * words, in a catalogue read by people typing Cyrillic. "toyota" spelled in
+ * Cyrillic and `Toyota` are the same word said in two scripts, and a
+ * `String.includes` over the caption answers "no" to every one of them. The
+ * autocatalog has 418 makes: without this, the search box in a dictionary
+ * facet is a box that works only for the half of the buyers whose keyboard
+ * matches the catalogue's.
+ *
+ * ── Two keys per word, and why the second one exists ──────────────────────
+ *
+ * The first key is a plain transliteration: Cyrillic → Latin through the table
+ * below, lowercased, everything but letters and digits dropped. That alone
+ * gets the Cyrillic spelling of "toyota" to `toiota` and `Toyota` to `toyota`
+ * — still not equal, and this is the general case rather than a bad table.
+ * Vowels are exactly where two scripts disagree: `i` against `y`, `e` against
+ * `a` in a borrowed word, `timberlend` against `timberland`. A vowel-perfect
+ * table does not exist, because the disagreement is in the borrowing, not in
+ * the letters.
+ *
+ * So the second key is the CONSONANT SKELETON: the first key with its vowels
+ * removed. `timberlend` and `timberland` are both `tmbrlnd`; `toiota` and
+ * `toyota` are both `tt`. Digits stay — a skeleton is about letters people
+ * disagree on, and `5` is not one.
+ *
+ * A candidate matches when either key of any of its WORDS starts with the
+ * corresponding key of the needle: a typed "rover" in either script finds
+ * `Land Rover`, and typing into the box narrows as you go, which is the whole
+ * point of a prefix rule. The skeleton arm is skipped for a needle that has no
+ * consonants at all — an empty skeleton is a prefix of everything, and a box
+ * that matches all 418 makes after one vowel is a box that has stopped
+ * answering.
+ *
+ * Table-driven and dependency-free on purpose: this is 40 pairs of characters,
+ * and a transliteration library is a page-weight decision made for a lookup
+ * table.
+ */
+/**
+ * One word, transliterated and folded to `[a-z0-9]`.
+ *
+ * `NFKD` + combining-mark strip first, so `Škoda` and `Skoda` are one word
+ * before anything else looks at them.
+ */
+export declare function translitKey(text: string): string;
+/** {@link translitKey} without its vowels — the key two spellings of one
+ * borrowed name agree on. */
+export declare function consonantKey(text: string): string;
+/**
+ * Does `candidate` answer the typed `needle`?
+ *
+ * Prefix, not substring: a dictionary of makes searched by substring puts
+ * `Great Wall` under `all`. Every word of the candidate is a starting point,
+ * and both keys are tried — see the module note.
+ */
+export declare function translitPrefixMatch(needle: string, candidate: string): boolean;
+//# sourceMappingURL=translit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"translit.d.ts","sourceRoot":"","sources":["../../src/state/translit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAuBH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYhD;AAED;6BAC6B;AAC7B,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAQD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU9E"}

package/dist/state/translit.js

@@ -0,0 +1,115 @@
+/**
+ * Matching a typed prefix against a dictionary value ACROSS ALPHABETS.
+ *
+ * A vocabulary of car makes holds `Toyota`, `Land Rover`, `Timberland` — Latin
+ * words, in a catalogue read by people typing Cyrillic. "toyota" spelled in
+ * Cyrillic and `Toyota` are the same word said in two scripts, and a
+ * `String.includes` over the caption answers "no" to every one of them. The
+ * autocatalog has 418 makes: without this, the search box in a dictionary
+ * facet is a box that works only for the half of the buyers whose keyboard
+ * matches the catalogue's.
+ *
+ * ── Two keys per word, and why the second one exists ──────────────────────
+ *
+ * The first key is a plain transliteration: Cyrillic → Latin through the table
+ * below, lowercased, everything but letters and digits dropped. That alone
+ * gets the Cyrillic spelling of "toyota" to `toiota` and `Toyota` to `toyota`
+ * — still not equal, and this is the general case rather than a bad table.
+ * Vowels are exactly where two scripts disagree: `i` against `y`, `e` against
+ * `a` in a borrowed word, `timberlend` against `timberland`. A vowel-perfect
+ * table does not exist, because the disagreement is in the borrowing, not in
+ * the letters.
+ *
+ * So the second key is the CONSONANT SKELETON: the first key with its vowels
+ * removed. `timberlend` and `timberland` are both `tmbrlnd`; `toiota` and
+ * `toyota` are both `tt`. Digits stay — a skeleton is about letters people
+ * disagree on, and `5` is not one.
+ *
+ * A candidate matches when either key of any of its WORDS starts with the
+ * corresponding key of the needle: a typed "rover" in either script finds
+ * `Land Rover`, and typing into the box narrows as you go, which is the whole
+ * point of a prefix rule. The skeleton arm is skipped for a needle that has no
+ * consonants at all — an empty skeleton is a prefix of everything, and a box
+ * that matches all 418 makes after one vowel is a box that has stopped
+ * answering.
+ *
+ * Table-driven and dependency-free on purpose: this is 40 pairs of characters,
+ * and a transliteration library is a page-weight decision made for a lookup
+ * table.
+ */
+/**
+ * Cyrillic → Latin, chosen for how the two scripts spell the SAME borrowed
+ * name rather than for a standard's fidelity: `kha` is `h` (Honda, not
+ * Khonda), `tse` is `c`, the two signs are nothing. Any letter absent here is
+ * kept as it is, so a Latin caption passes through untouched. Keys are
+ * quoted — the fleet's source is English, and a Cyrillic identifier is not.
+ */
+const CYRILLIC_TO_LATIN = {
+    "а": "a", "б": "b", "в": "v", "г": "g", "д": "d", "е": "e", "ё": "e",
+    "ж": "zh", "з": "z", "и": "i", "й": "i", "к": "k", "л": "l", "м": "m",
+    "н": "n", "о": "o", "п": "p", "р": "r", "с": "s", "т": "t", "у": "u",
+    "ф": "f", "х": "h", "ц": "c", "ч": "ch", "ш": "sh", "щ": "sh", "ъ": "",
+    "ы": "y", "ь": "", "э": "e", "ю": "u", "я": "a",
+    // Ukrainian/Belarusian letters a shared vocabulary can carry.
+    "і": "i", "ї": "i", "є": "e", "ґ": "g", "ў": "u",
+};
+/** Vowels of the transliterated form — `y` included, because it stands for a
+ * Cyrillic semi-vowel as often as it stands for a consonant. */
+const VOWELS = new Set(["a", "e", "i", "o", "u", "y"]);
+/**
+ * One word, transliterated and folded to `[a-z0-9]`.
+ *
+ * `NFKD` + combining-mark strip first, so `Škoda` and `Skoda` are one word
+ * before anything else looks at them.
+ */
+export function translitKey(text) {
+    const folded = text
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase();
+    let out = "";
+    for (const char of folded) {
+        const mapped = CYRILLIC_TO_LATIN[char];
+        if (mapped !== undefined)
+            out += mapped;
+        else if (/[a-z0-9]/.test(char))
+            out += char;
+    }
+    return out;
+}
+/** {@link translitKey} without its vowels — the key two spellings of one
+ * borrowed name agree on. */
+export function consonantKey(text) {
+    let out = "";
+    for (const char of translitKey(text))
+        if (!VOWELS.has(char))
+            out += char;
+    return out;
+}
+/** The words of a caption, split on everything that is not a letter or a
+ * digit — so `Land Rover` is reachable by "rover" in either script. */
+function words(text) {
+    return text.split(/[^\p{L}\p{N}]+/u).filter((word) => word.length > 0);
+}
+/**
+ * Does `candidate` answer the typed `needle`?
+ *
+ * Prefix, not substring: a dictionary of makes searched by substring puts
+ * `Great Wall` under `all`. Every word of the candidate is a starting point,
+ * and both keys are tried — see the module note.
+ */
+export function translitPrefixMatch(needle, candidate) {
+    const key = translitKey(needle);
+    if (key.length === 0)
+        return true;
+    const skeleton = consonantKey(needle);
+    for (const word of [candidate, ...words(candidate)]) {
+        const wordKey = translitKey(word);
+        if (wordKey.startsWith(key))
+            return true;
+        if (skeleton.length > 0 && consonantKey(word).startsWith(skeleton))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=translit.js.map

package/dist/state/translit.js.map

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

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/search-react 0.21.0
+# @stapel/search-react 0.23.0
 
 Headless React flow pair for stapel-search (contract >=0.14 <0.15) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
@@ -85,6 +85,8 @@ const { tracked } = useTracked();
 - search.location-summary → <LocationSummaryLine> [everywhere|placed|narrowed|long-place|wide]  demo/LocationSummaryLine.demo.tsx
 - search.page → <SearchPage> [desktop|phone|unreadable-link]  demo/SearchPage.demo.tsx
 - search.page-size-select → <PageSizeSelect> [ladder|off-ladder]  demo/PageSizeSelect.demo.tsx
+- search.partition-chips → <PartitionChips> [parent|child]  demo/PartitionChips.demo.tsx
+- search.popular-values → <PopularValues> [desktop|narrow-column]  demo/PopularValues.demo.tsx
 - search.range-filter-row → <RangeFilterRow> [untouched|applied]  demo/RangeFilterRow.demo.tsx
 - search.ranking-pane → <RankingDisclosurePane> [desktop|phone]  demo/RankingDisclosurePane.demo.tsx
 - search.result-card → <SearchResultCard> [gallery|promoted|unresolved|plain]  demo/SearchResultCard.demo.tsx

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.21.0",
+  "version": "0.23.0",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.14 <0.15"
@@ -573,6 +573,31 @@
       ],
       "source": "demo/PageSizeSelect.demo.tsx"
     },
+    {
+      "id": "search.partition-chips",
+      "title": "Partition chips",
+      "description": "A single-select row of the parent plus its children, where the first chip is the parent itself rather than a way of clearing the others — searching the parent IS the union of its children. It is a real radiogroup with roving tabindex: Tab reaches the row once and lands on the chosen chip, the arrow keys move along it and choose as they go. A row of aria-pressed toggles would announce the opposite — independent switches, with no reason why pressing one released another.",
+      "component": "PartitionChips",
+      "variants": [
+        "parent",
+        "child"
+      ],
+      "source": "demo/PartitionChips.demo.tsx"
+    },
+    {
+      "id": "search.popular-values",
+      "title": "Popular values",
+      "description": "The head of one facet as a multi-column list of value + count, each line applying that filter. The numbers are the answer's own drill-down counts — the same ones the checkbox rows carry — so a value cannot read 802 here and 93 in the panel. Values with no evidence behind them are dropped rather than printed with a blank where the number belongs: the block IS the numbers. Whether a phone has room for it is the page's decision and arrives as the `hidden` prop, never as a media query inside.",
+      "component": "PopularValues",
+      "tokens": [
+        "text-muted"
+      ],
+      "variants": [
+        "desktop",
+        "narrow-column"
+      ],
+      "source": "demo/PopularValues.demo.tsx"
+    },
     {
       "id": "search.range-filter-row",
       "title": "Numeric range filter",
@@ -756,9 +781,14 @@
     "search.empty.up_a_level",
     "search.empty.widen_radius",
     "search.error.unknown",
+    "search.facets.all_filters",
     "search.facets.approximate",
     "search.facets.clear",
     "search.facets.clear_all",
+    "search.facets.dictionary_any",
+    "search.facets.dictionary_chosen",
+    "search.facets.dictionary_empty",
+    "search.facets.dictionary_search",
     "search.facets.drill_down_hint",
     "search.facets.empty",
     "search.facets.load_failed",
@@ -767,7 +797,9 @@
     "search.facets.match_count.one",
     "search.facets.match_count.other",
     "search.facets.not_counted",
+    "search.facets.popular_all",
     "search.facets.range_apply",
+    "search.facets.range_bounds",
     "search.facets.range_clear",
     "search.facets.range_from",
     "search.facets.range_from_aria",
@@ -815,6 +847,8 @@
     "search.nav.ranking",
     "search.nav.ranking.short",
     "search.nav.results",
+    "search.partition.all",
+    "search.partition.label",
     "search.range.price",
     "search.ranking.applies_to",
     "search.ranking.empty",
@@ -880,6 +914,7 @@
       "FILTER_PREFIX",
       "FacetPanel",
       "RANGE_FEATURE_TYPES",
+      "RANGE_PICKER_MAX_VALUES",
       "RANGE_PREFIX",
       "RankingDisclosure",
       "SEARCH_BACKEND_UNAVAILABLE",
@@ -909,6 +944,7 @@
       "buildFacetGroups",
       "buildRangeGroups",
       "clearFilters",
+      "consonantKey",
       "coreRangeLabelKey",
       "countIsEstimate",
       "countKind",
@@ -918,6 +954,8 @@
       "degradationAudience",
       "degradationMessageKey",
       "explainSearchError",
+      "facetGroupHasEvidence",
+      "facetGroupIsDrawable",
       "facetOptionLabel",
       "isCountNuanceOnly",
       "isFacetableFeature",
@@ -925,6 +963,7 @@
       "isRangeUsable",
       "navEntries",
       "offerableCategories",
+      "orderFacetGroupsBySchema",
       "ownsParam",
       "parseDegradations",
       "parseSearchState",
@@ -939,6 +978,8 @@
       "setRangeValue",
       "suggestTerms",
       "toggleFilterValue",
+      "translitKey",
+      "translitPrefixMatch",
       "useAppliedSort",
       "useFacetPanel",
       "useHostFacetLabels",
@@ -961,6 +1002,9 @@
       "FacetGroup",
       "FacetLabelRequest",
       "FacetLabelResolver",
+      "FacetLabelSource",
+      "FacetLabels",
+      "FacetLabelsMap",
       "FacetMeta",
       "FacetOption",
       "FacetPanelBag",

package/nav-manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.21.0",
+  "version": "0.23.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 and the host label seam): no antd, no react-router",
+      "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",
       "path": "dist/index.js",
-      "limit": "11.5 KB"
+      "limit": "12.5 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) must stay out of the main bundle",
+      "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",
       "path": "dist/default/index.js",
-      "limit": "22.5 KB"
+      "limit": "25.5 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -69,7 +69,7 @@
     {
       "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
       "path": "dist/i18n/ru.js",
-      "limit": "4.5 KB"
+      "limit": "4.75 KB"
     },
     {
       "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry",
@@ -115,8 +115,8 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.14.1",
-    "@stapel/core": "^0.24.0",
+    "@stapel/attributes-react": "^0.15.0",
+    "@stapel/core": "^0.25.0",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.7.0",

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.21.0",
+  "version": "0.23.0",
   "defined": [],
   "flows": []
 }

package/src/api/types.ts

@@ -13,10 +13,49 @@ import type { components } from "./generated/schema.js";
 /** The generated schema table — the one source of truth for wire shapes. */
 export type Schemas = components["schemas"];
 
-/** `GET /query` 200 — the whole envelope. Corrected in one place: see
- * {@link FacetMeta}. */
-export type SearchResponse = Omit<Schemas["SearchResponse"], "facet_meta"> & {
+/**
+ * One slug's captions: the GROUP's own name, and the words for its values.
+ *
+ * `label` is the group heading the server resolved from the category's
+ * feature definition, in the request's own language. It is the only source
+ * that always exists — `categoryFeatures` is an optional slot a live
+ * classified board never filled, and without it every heading in the panel
+ * was the raw index slug. `null` is the server saying it has no name for the
+ * 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.
+ */
+export type FacetLabels = Schemas["FacetLabels"] & {
+  readonly label?: string | null;
+  /**
+   * Whether {@link label} is a translation KEY rather than a caption, the way
+   * `translatable` says it for the values.
+   *
+   * Measured on a live answer (`category=141/151`, 2026-09-04): the server
+   * sends it beside every label — a make caption with
+   * `label_translatable: false`, a condition caption with `true` — and the
+   * describe it. Declared, not consumed: this pair passes the group heading
+   * through its translator either way, and a caption that is not a key comes
+   * back unchanged (`translate()` keeps a key it cannot resolve). Typed so a
+   * fixture captured from the wire is not a type error.
+   */
+  readonly label_translatable?: boolean;
+};
+
+/** `facet_labels` as a whole: `{slug: {label, translatable, values}}`. */
+export type FacetLabelsMap = Readonly<Record<string, FacetLabels>>;
+
+/** `GET /query` 200 — the whole envelope. Corrected in two places: see
+ * {@link FacetMeta} and {@link FacetLabels}. */
+export type SearchResponse = Omit<
+  Schemas["SearchResponse"],
+  "facet_meta" | "facet_labels"
+> & {
   readonly facet_meta: FacetMeta;
+  readonly facet_labels: FacetLabelsMap;
 };
 
 /** One result row. `promoted` is present on EVERY item under EVERY sort — a