@stapel/search-react 0.21.0 → 0.22.0

package/src/i18n/keys.ts

@@ -157,6 +157,24 @@ export const SEARCH_I18N_KEYS = {
    * Distinct from `facetsEmpty`, which says the SEARCH offers no filters —
    * here the filters exist and the query missed. */
   facetsSearchEmpty: "search.facets.search_empty",
+  /**
+   * The box inside ONE dictionary group — 418 car makes are not a list a
+   * person scrolls. Distinct from `facetsSearch`, which finds a GROUP among
+   * forty headings: one narrows the panel, the other narrows one axis of it,
+   * and a translator handed one string for both has to pick which surface to
+   * be wrong on.
+   */
+  facetsDictionarySearch: "search.facets.dictionary_search",
+  /** The dictionary box matched no value of this group. Not `facetsEmpty`,
+   * and not `facetsSearchEmpty`: the group exists and its values exist. */
+  facetsDictionaryEmpty: "search.facets.dictionary_empty",
+  /** Over the values already chosen, which stay visible whatever the box
+   * says — a filter a person cannot see is a filter they cannot remove. */
+  facetsDictionaryChosen: "search.facets.dictionary_chosen",
+  /** The way from the "popular values" block into the whole control. The
+   * block is a shortcut over the busiest values, so the link has to say that
+   * the rest exist. */
+  facetsPopularAll: "search.facets.popular_all",
   /**
    * The rail's sticky footer: what the applied filters LEFT — "N listings
    * match". A PLURAL FAMILY: it counts a noun in words. Desktop filters
@@ -192,6 +210,20 @@ export const SEARCH_I18N_KEYS = {
    * `{count}` is how many chips it hides (D16). */
   filtersChipOverflow: "search.filters.chips_overflow",
 
+  // ── a partition: one template split by a value its children name ─────────
+  /**
+   * The first chip of a partition row — the parent itself, unnarrowed.
+   *
+   * Not `facetsPopularAll` reused: that one OPENS a control, this one is a
+   * CHOICE among the children (and the one that is selected by default). The
+   * two are the same word in English and stop being one the moment a
+   * translator reads either as an imperative.
+   */
+  partitionAll: "search.partition.all",
+  /** The accessible name of the chip row — a `radiogroup` with no name is
+   * announced as nothing at all. */
+  partitionLabel: "search.partition.label",
+
   // ── the way OUT of a search that found nothing ───────────────────────────
   /** Caption above the exit buttons. Not a second "nothing found" — that
    * sentence has already been said; this one says what can be done next. */
@@ -462,6 +494,12 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.show_less": "Show fewer",
   "search.facets.search": "Find a filter",
   "search.facets.search_empty": "No filter matches this",
+  "search.facets.dictionary_search": "Find a value",
+  "search.facets.dictionary_empty": "No value matches this",
+  "search.facets.dictionary_chosen": "Chosen",
+  "search.facets.popular_all": "All",
+  "search.partition.all": "All",
+  "search.partition.label": "Section",
   "search.facets.match_count.one": "{count} listing matches",
   "search.facets.match_count.other": "{count} listings match",
   "search.facets.range_invalid":

package/src/i18n/ru.ts

@@ -122,6 +122,12 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.show_less": "Свернуть",
   "search.facets.search": "Найти фильтр",
   "search.facets.search_empty": "Среди фильтров такого нет",
+  "search.facets.dictionary_search": "Найти значение",
+  "search.facets.dictionary_empty": "Такого значения здесь нет",
+  "search.facets.dictionary_chosen": "Выбрано",
+  "search.facets.popular_all": "Все",
+  "search.partition.all": "Все",
+  "search.partition.label": "Раздел",
   "search.facets.match_count.one": "Найдено {count} объявление",
   "search.facets.match_count.few": "Найдено {count} объявления",
   "search.facets.match_count.many": "Найдено {count} объявлений",

package/src/index.ts

@@ -52,6 +52,8 @@ export {
 } from "./api/types.js";
 export type {
   FacetCategoryCount,
+  FacetLabels,
+  FacetLabelsMap,
   FacetMeta,
   FacetSelection,
   FacetWithheldGroup,
@@ -120,9 +122,16 @@ export {
 export type {
   BuildFacetGroupsInput,
   FacetGroup,
+  FacetLabelSource,
   FacetOption,
 } from "./state/facets.js";
 
+export {
+  consonantKey,
+  translitKey,
+  translitPrefixMatch,
+} from "./state/translit.js";
+
 export {
   RANGE_FEATURE_TYPES,
   buildRangeGroups,

package/src/state/facets.ts

@@ -8,9 +8,12 @@
  *    they would have if you swapped to them. A panel that greys the siblings
  *    out has silently converted a drill-down facet into a naive one, and the
  *    e2e leg in the spec (§7.2) exists to catch exactly that.
- * 2. **Option LABELS have one stated order: ANSWER, then schema, then the
- *    raw value** — with a host resolver between the last two, applied by
- *    `useHostFacetLabels` on what this module could not name.
+ * 2. **LABELS have one stated order: ANSWER, then schema, then the raw
+ *    term** — for the group's heading and for every option alike, with a host
+ *    resolver between the last two for options, applied by
+ *    `useHostFacetLabels` on what this module could not name. The bottom of
+ *    that order is not a label and is marked as such: `labelSource: "none"`,
+ *    a warning in development, and a data attribute on the drawn group.
  *
  *    The answer leads because it is the only source that always exists and
  *    the only one that has RESOLVED anything: `categoryFeatures` is an
@@ -50,12 +53,48 @@
 import {
   VOCABULARY_BACKED_TYPES,
   featureConfig,
-  featureName,
   featureType,
   formatFeatureValue,
 } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
-import type { FacetMeta, SearchQueryState } from "../api/types.js";
+import type { FacetLabelsMap, FacetMeta, SearchQueryState } from "../api/types.js";
+
+/**
+ * Where a caption came from — the group's heading and every option carry it,
+ * because "did anybody actually name this?" is a question two surfaces have
+ * to answer and neither can answer by looking at the string.
+ *
+ * `"none"` is the honest bottom: the raw slug for a heading, the raw index
+ * term for an option. It is not a label, it is what is printed when there is
+ * none, and it is the one value a storefront's own test asserts against.
+ */
+export type FacetLabelSource = "server" | "schema" | "host" | "none";
+
+declare const process: { readonly env: { readonly NODE_ENV?: string } };
+
+/** Slugs already complained about — one warning per slug per page load, not
+ * one per render. */
+const warnedSlugs = new Set<string>();
+
+/**
+ * A heading nobody named, said once, in development only.
+ *
+ * A raw slug in a filter panel is a wiring fault — the category has no
+ * feature definition for the slug and the server sent no label — and it is
+ * invisible to everyone but the buyer who meets it. The group still renders,
+ * because a heading a person cannot read still beats options with no heading
+ * at all; `FacetGroup.labelSource` is how a surface marks it up for a test.
+ */
+function warnUnnamedGroup(slug: string): void {
+  const env = typeof process === "undefined" ? undefined : process.env;
+  if (env?.NODE_ENV === "production") return;
+  if (warnedSlugs.has(slug)) return;
+  warnedSlugs.add(slug);
+  console.warn(
+    `[search-react] facet group "${slug}" has no label: the answer sent none ` +
+      `and no category feature defines it, so the heading is the raw slug.`
+  );
+}
 
 /**
  * Value types whose values are a BOUNDED OPTION SET — the only kind of
@@ -111,14 +150,22 @@ export interface FacetOption {
   readonly count: number | null;
   /** Resolved through the category schema; the raw value when there is none. */
   readonly label: string;
+  /** Which of the three sources named it — `"none"` means {@link label} IS
+   * the raw index term. The host seam reads this rather than comparing the
+   * two strings. */
+  readonly labelSource: FacetLabelSource;
   readonly selected: boolean;
 }
 
 /** One facet slug, with its options. */
 export interface FacetGroup {
   readonly slug: string;
-  /** The feature's display name (translated when it is a key), else the slug. */
+  /** The group's heading: the answer's own `label`, else the feature's
+   * display name, else — with a dev warning — the raw slug. */
   readonly label: string;
+  /** Which source named the heading. `"none"` is the slug standing in for a
+   * name nobody has; a surface marks it so a storefront test can fail on it. */
+  readonly labelSource: FacetLabelSource;
   /** The category-schema entry behind the slug, when the host supplied one. */
   readonly feature: FeatureDef | undefined;
   /** `false` when the server skipped this slug — counts are `null`. */
@@ -199,17 +246,17 @@ export interface BuildFacetGroupsInput {
    *    `apple` or `chernyy`. The server read that vocabulary against the
    *    snapshot the documents were written with.
    *
+   * Each entry also carries the GROUP's own `label` — the heading, resolved
+   * from the feature definition server-side and localized like everything
+   * else. It leads for the same two reasons, and it is what a category whose
+   * host passed no feature list has instead of a rail full of index slugs.
+   *
    * ABSENT on a server older than 0.4.0 — absent, not empty — which is why
    * every read of it here is optional-chained and every option falls through
    * to the schema and then to its raw self. No labels are invented at any
    * step.
    */
-  readonly facetLabels?: Readonly<
-    Record<
-      string,
-      { readonly translatable: boolean; readonly values: Readonly<Record<string, string>> }
-    >
-  >;
+  readonly facetLabels?: FacetLabelsMap;
   /** Translator for label keys. */
   readonly t?: (key: string) => string;
   /** BCP-47 tag, forwarded to `formatFeatureValue` for `date` options. */
@@ -287,11 +334,49 @@ function resolveLabel(
   slug: string,
   value: string,
   labelOptions: { t?: (key: string) => string; locale?: string }
-): string {
-  return (
-    serverLabel(input.facetLabels, slug, value, input.t) ??
-    facetOptionLabel(feature, value, labelOptions)
-  );
+): { readonly label: string; readonly labelSource: FacetLabelSource } {
+  const answer = serverLabel(input.facetLabels, slug, value, input.t);
+  if (answer !== undefined) return { label: answer, labelSource: "server" };
+  const schema = facetOptionLabel(feature, value, labelOptions);
+  // `facetOptionLabel` hands back the value unchanged for an option it
+  // cannot name, and that identity is the whole test — a formatter that
+  // returned the term is a formatter that named nothing.
+  return schema === value
+    ? { label: value, labelSource: "none" }
+    : { label: schema, labelSource: "schema" };
+}
+
+/**
+ * The group's HEADING, in the one order the fleet states: the answer, then
+ * the category schema, then the slug under a dev warning.
+ *
+ * The answer leads because it is the only source that always exists. The
+ * schema slot is optional, and at a live classified's cars branch the
+ * storefront passed an empty feature list, so every heading in the rail was
+ * a raw index slug — the make group was on screen, unlabelled, and the
+ * complaint that came back was "I cannot pick a make".
+ *
+ * The slug is not a fallback anyone may ship: it renders, because a heading
+ * beats no heading, and it renders MARKED — `labelSource: "none"`, a warning
+ * in development, and a data attribute on the drawn group.
+ */
+function resolveGroupLabel(
+  input: BuildFacetGroupsInput,
+  feature: FeatureDef | undefined,
+  slug: string
+): { readonly label: string; readonly labelSource: FacetLabelSource } {
+  const answer = input.facetLabels?.[slug]?.label;
+  if (typeof answer === "string" && answer.length > 0) {
+    return { label: translate(input.t, answer), labelSource: "server" };
+  }
+  // `featureName` falls back to the slug itself, so the def has to be asked
+  // for a NAME rather than for a name-or-slug: a def with none names nothing.
+  const declared = feature?.name;
+  if (typeof declared === "string" && declared.length > 0) {
+    return { label: translate(input.t, declared), labelSource: "schema" };
+  }
+  warnUnnamedGroup(slug);
+  return { label: slug, labelSource: "none" };
 }
 
 /**
@@ -446,22 +531,17 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
 
     return {
       slug,
-      label:
-        feature === undefined
-          ? slug
-          : translate(input.t, featureName(feature)),
+      ...resolveGroupLabel(input, feature, slug),
       feature,
       counted,
       selected,
       options: values.map((value) => ({
         value,
         count: counted ? (counts[value] ?? 0) : null,
-        // The host's schema first when it actually resolves the value, the
-        // answer's caption when it does not (or when there is no schema at
-        // all), the raw value when neither knows. `facetOptionLabel` returns
-        // the value unchanged for an option it cannot name, which is what
-        // makes "did it resolve?" answerable without a second lookup.
-        label: resolveLabel(input, feature, slug, value, labelOptions),
+        // The answer's caption first, then the schema's own option table,
+        // then the raw value — and the source is carried rather than
+        // re-derived, so "did it resolve?" needs no second lookup.
+        ...resolveLabel(input, feature, slug, value, labelOptions),
         selected: selected.includes(value),
       })),
     };

package/src/state/translit.ts

@@ -0,0 +1,113 @@
+/**
+ * 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: Readonly<Record<string, string>> = {
+  "а": "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: string): string {
+  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: string): string {
+  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: string): readonly string[] {
+  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: string, candidate: string): boolean {
+  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;
+}