@stapel/search-react 0.20.0 → 0.22.0

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;
+}

package/src/state/urlState.ts

@@ -74,19 +74,45 @@ export type SearchStateIssueCode =
   /** `bbox` was not four numbers. */
   | "bbox_malformed"
   /** `r.<slug>` was not `from..to`. */
-  | "range_malformed";
+  | "range_malformed"
+  /**
+   * `radius_km` with nothing to measure it FROM — no `lat`/`lon`, no `bbox`.
+   *
+   * Not malformed: `radius_km=300` is a perfectly good number, and the search
+   * that ran is the honest one (a radius with no centre narrows nothing, so
+   * the count is the full count). What was wrong was the SILENCE. The URL said
+   * 300km, the results were unnarrowed, and the location control went on
+   * advertising its own default — measured on a live leaf as "300 in the
+   * address bar, 25 on the screen" with no way for a person to tell which one
+   * the page had used. Neither number is dropped and neither is rewritten;
+   * the disagreement is simply stated.
+   */
+  | "radius_without_place";
 
 const ISSUE_KEY: Readonly<Record<SearchStateIssueCode, string>> = {
   not_a_number: "search.url.issue.not_a_number",
   geo_incomplete: "search.url.issue.geo_incomplete",
   bbox_malformed: "search.url.issue.bbox_malformed",
   range_malformed: "search.url.issue.range_malformed",
+  radius_without_place: "search.url.issue.radius_without_place",
 };
 
 /** What {@link parseSearchState} answers: the state, plus what it could not read. */
 export interface ParsedSearchState {
   readonly state: SearchQueryState;
   readonly issues: readonly SearchStateIssue[];
+  /**
+   * A `radius_km` the URL carries with no place to measure it from.
+   *
+   * NOT part of the state — a radius with no centre is not a filter and
+   * nothing is sent to the server — but it is a number the person typed, and
+   * dropping it on the floor is how the control and the address ended up
+   * disagreeing: `?radius_km=300`, a button offering "within 25 km", and a
+   * press that silently rewrote 300 to 25. Whoever draws the offer reads this
+   * so that what the button SAYS, what pressing it DOES, and what the link
+   * ASKED FOR are one number.
+   */
+  readonly orphanRadiusKm?: number;
 }
 
 export interface ParseSearchStateOptions {
@@ -122,10 +148,16 @@ function num(
   return value;
 }
 
+/** Where `parseGeo` leaves a radius it could not attach to anything. */
+interface GeoParse {
+  readonly geo: SearchGeo | undefined;
+  readonly orphanRadiusKm?: number;
+}
+
 function parseGeo(
   params: URLSearchParams,
   issues: SearchStateIssue[]
-): SearchGeo | undefined {
+): GeoParse {
   const bbox = params.get(SEARCH_PARAM.bbox);
   if (bbox !== null) {
     const parts = bbox.split(",");
@@ -135,7 +167,7 @@ function parseGeo(
         code: "bbox_malformed",
         messageKey: ISSUE_KEY.bbox_malformed,
       });
-      return undefined;
+      return { geo: undefined };
     }
     const values = parts.map((p) => Number(p));
     if (values.some((v) => !Number.isFinite(v))) {
@@ -144,43 +176,64 @@ function parseGeo(
         code: "bbox_malformed",
         messageKey: ISSUE_KEY.bbox_malformed,
       });
-      return undefined;
+      return { geo: undefined };
     }
     // `minLon > maxLon` is LEGAL — it means the box crosses the antimeridian
     // (`stapel-search/query.py`). Normalizing it here would silently turn a
     // Pacific search into the rest of the world.
     return {
+      geo: {
       kind: "bbox",
       minLat: values[0] as number,
       minLon: values[1] as number,
       maxLat: values[2] as number,
       maxLon: values[3] as number,
+      },
     };
   }
 
   const rawLat = params.get(SEARCH_PARAM.lat);
   const rawLon = params.get(SEARCH_PARAM.lon);
-  if (rawLat === null && rawLon === null) return undefined;
+  if (rawLat === null && rawLon === null) {
+    // A radius parked in the URL with no point to measure it from. See
+    // `radius_without_place`: the search below is correct, the screen was the
+    // liar.
+    const orphan = params.get(SEARCH_PARAM.radiusKm);
+    if (orphan !== null) {
+      issues.push({
+        param: SEARCH_PARAM.radiusKm,
+        code: "radius_without_place",
+        messageKey: ISSUE_KEY.radius_without_place,
+      });
+      const km = Number(orphan);
+      if (Number.isFinite(km) && km > 0) {
+        return { geo: undefined, orphanRadiusKm: km };
+      }
+    }
+    return { geo: undefined };
+  }
   if (rawLat === null || rawLon === null) {
     issues.push({
       param: rawLat === null ? SEARCH_PARAM.lat : SEARCH_PARAM.lon,
       code: "geo_incomplete",
       messageKey: ISSUE_KEY.geo_incomplete,
     });
-    return undefined;
+    return { geo: undefined };
   }
   const lat = num(rawLat, SEARCH_PARAM.lat, issues);
   const lon = num(rawLon, SEARCH_PARAM.lon, issues);
-  if (lat === undefined || lon === undefined) return undefined;
+  if (lat === undefined || lon === undefined) return { geo: undefined };
 
   const rawRadius = params.get(SEARCH_PARAM.radiusKm);
   const radiusKm =
     rawRadius === null ? undefined : num(rawRadius, SEARCH_PARAM.radiusKm, issues);
   return {
-    kind: "center",
-    lat,
-    lon,
-    ...(radiusKm !== undefined ? { radiusKm } : {}),
+    geo: {
+      kind: "center",
+      lat,
+      lon,
+      ...(radiusKm !== undefined ? { radiusKm } : {}),
+    },
   };
 }
 
@@ -246,6 +299,8 @@ export function parseSearchState(
   const direction: "next" | "prev" | undefined =
     rawDirection === null ? undefined : rawDirection === "prev" ? "prev" : "next";
 
+  const geoParse = parseGeo(params, issues);
+
   const state: SearchQueryState = {
     type: params.get(SEARCH_PARAM.type) ?? options.defaultType,
     q: params.get(SEARCH_PARAM.q) ?? options.defaultQ ?? "",
@@ -257,7 +312,7 @@ export function parseSearchState(
       params.get(SEARCH_PARAM.category) ?? options.defaultCategory
     ),
     ...optional(SEARCH_PARAM.owner, params.get(SEARCH_PARAM.owner) ?? undefined),
-    ...optional("geo", parseGeo(params, issues)),
+    ...optional("geo", geoParse.geo),
     ...optional(
       SEARCH_PARAM.sort,
       params.get(SEARCH_PARAM.sort) ?? options.defaultSort
@@ -268,7 +323,11 @@ export function parseSearchState(
     ...optional("limit", limit),
   };
 
-  return { state, issues };
+  return {
+    state,
+    issues,
+    ...optional("orphanRadiusKm", geoParse.orphanRadiusKm),
+  };
 }
 
 /** `exactOptionalPropertyTypes` makes `{k: undefined}` and "absent" different