@stapel/search-react 0.10.0 → 0.12.0

package/src/model/queryKeys.ts

@@ -32,6 +32,22 @@ export const searchQueryKeys: {
   query(
     params: SearchQueryKeyParams
   ): readonly ["search", "query", SearchQueryKeyParams];
+  /**
+   * One group's captions from the HOST's resolver — the seam that names a
+   * vocabulary-backed facet value on a server too old to caption it itself.
+   *
+   * Keyed on the slug, the values asked about and the locale. The values are
+   * SORTED by the caller before they get here: the same group arrives in
+   * count order, and count order changes on every click, so an unsorted key
+   * would re-ask the host for the same words each time a sibling facet moved.
+   * The locale is in the key because a caption is copy — one cache entry per
+   * language, never one shared between two.
+   */
+  facetLabels(
+    slug: string,
+    values: readonly string[],
+    locale?: string
+  ): readonly ["search", "facet-labels", string, readonly string[], string | null];
   /** The P2B disclosure. `type` is optional on the endpoint; normalized to
    * `null` so an absent type and an explicit `undefined` cannot cache twice. */
   ranking(type?: string): readonly ["search", "ranking", string | null];
@@ -43,6 +59,13 @@ export const searchQueryKeys: {
 } = {
   all: [ROOT],
   query: (params) => [ROOT, "query", params],
+  facetLabels: (slug, values, locale) => [
+    ROOT,
+    "facet-labels",
+    slug,
+    values,
+    locale ?? null,
+  ],
   ranking: (type) => [ROOT, "ranking", type ?? null],
   suggest: (type, q, limit) => [ROOT, "suggest", type, q, limit ?? null],
 };

package/src/nav/manifest.ts

@@ -15,13 +15,34 @@
  * `menuVisibleDefault: false` on both: the results page is a navigation TARGET
  * reached from the header's search box, and the ranking disclosure is a
  * footer link. Neither is a menu item — the same treatment `auth.login` gets.
+ *
+ * ── A nav label is not a page heading ─────────────────────────────────────
+ *
+ * Both entries carry their OWN label keys (`search.nav.*`) rather than
+ * borrowing the surfaces' captions. `search.results.title` is the heading over
+ * a list of matches, so it reads "Results" — correct above rows, and useless
+ * in a menu, where "Results" answers nothing about where the link goes. The
+ * destination is the search. `search.ranking.title` is worse in the other
+ * direction: it is a whole sentence ("How these results are ordered"), which
+ * is right on the page it captions and cannot be a menu row.
+ *
+ * Sharing one key would also make the two uses move together forever: a
+ * translator improving the heading would silently rewrite the menu, and there
+ * is no locale in which the best heading and the best menu label are reliably
+ * the same words.
+ *
+ * `shortLabelKey` on the disclosure for the same reason one step smaller: a
+ * five-cell phone dock gives a destination roughly ten characters, and
+ * "Ranking disclosure" ellipsizes there to a fragment a person has to guess
+ * at. `search.results` declares none — its label is already one word in every
+ * locale this pair ships.
  */
 import type { NavEntry } from "@stapel/core";
 
 export const navEntries: readonly NavEntry[] = [
   {
     id: "search.results",
-    labelKey: "search.results.title",
+    labelKey: "search.nav.results",
     icon: "SearchOutlined",
     route: { path: "/s" },
     component: { export: "SearchPage", subpath: "default" },
@@ -40,7 +61,8 @@ export const navEntries: readonly NavEntry[] = [
     // be mistaken — by a person or by `stapel/no-string-paths` — for the API
     // operation of the same name.
     id: "search.ranking",
-    labelKey: "search.ranking.title",
+    labelKey: "search.nav.ranking",
+    shortLabelKey: "search.nav.ranking.short",
     icon: "OrderedListOutlined",
     route: { path: "/ranking-disclosure" },
     component: { export: "RankingDisclosurePane", subpath: "default" },

package/src/state/degradations.ts

@@ -133,3 +133,59 @@ export function isCountNuanceOnly(
     degradations.every((degradation) => degradation.kind === "exact_total")
   );
 }
+
+/**
+ * Who a degradation is addressed to.
+ *
+ * - `"reader"` — it changes what THIS PAGE MEANS. "Counts are approximate",
+ *   "subcategories may be missing", "a ranking parameter is inactive", and
+ *   anything this build has no wording for. A buyer can act on these: read
+ *   the numbers as estimates, widen the category, distrust the order.
+ * - `"operator"` — it describes the ENGINE THIS DEPLOYMENT CHOSE. Nothing a
+ *   buyer does changes it, and it is the same sentence on every query
+ *   forever, which is precisely what makes it invisible by the time it
+ *   matters.
+ */
+export type SearchDegradationAudience = "reader" | "operator";
+
+const OPERATOR_KINDS: ReadonlySet<string> = new Set<SearchDegradationKind>([
+  // Both of these say, in the shipped copy, "the search engine in use
+  // cannot do this" — a sentence about a procurement decision, printed at a
+  // person trying to buy a phone.
+  "typo_tolerance",
+  "phrase_synonyms",
+  // A count nuance the count itself already speaks, as "N+". This is the
+  // rule `isCountNuanceOnly` encoded for one kind, generalized.
+  "exact_total",
+]);
+
+/** {@link SearchDegradationAudience} for one kind. */
+export function degradationAudience(
+  kind: SearchDegradationKind
+): SearchDegradationAudience {
+  return OPERATOR_KINDS.has(kind) ? "operator" : "reader";
+}
+
+/**
+ * The degradations a buyer should be told about.
+ *
+ * The live defect this exists for: a classified board raised a full-screen
+ * yellow "What this search could not do: synonyms were not substituted —
+ * the search engine in use cannot do this" between the sort control and
+ * the first card, on every query, for every buyer. It was not a lie about a
+ * broken thing — stapel-search really did report `phrase_synonyms` on every
+ * query with text — which is exactly why deleting the STRING would have been
+ * the wrong fix: the next engine-capability literal would have grown its own
+ * copy of it. What is wrong is the AUDIENCE, so the audience is the thing
+ * that got a name.
+ *
+ * `variant="debug"` on `<DegradationNotice>` shows the operator's half; a
+ * host that wants it on a status page renders that.
+ */
+export function readerFacing(
+  degradations: readonly SearchDegradation[]
+): readonly SearchDegradation[] {
+  return degradations.filter(
+    (degradation) => degradationAudience(degradation.kind) === "reader"
+  );
+}

package/src/state/facets.ts

@@ -8,22 +8,95 @@
  *    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. **The server does not send option LABELS** (`facets.py` returns
- *    `{value: count}` and nothing else). The labels are in the category's
- *    feature schema, which is why {@link buildFacetGroups} takes
- *    `categoryFeatures` — the second slot-seam of the pair, filled by the
- *    container from `categories-react` (spec §6.2 item 2). Without it the
- *    panel still works and shows raw values; it does not invent labels.
+ * 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.
+ *
+ *    The answer leads because it is the only source that always exists and
+ *    the only one that has RESOLVED anything: `categoryFeatures` is an
+ *    optional slot a live classified board never filled, and even where it is
+ *    filled a `ref_select` config carries a pointer to a vocabulary and no
+ *    option table at all — so the schema cannot name `apple` or `chernyy` no
+ *    matter who threads it through. `facet_labels` (stapel-search 0.4.0+,
+ *    vocabulary-backed from 0.6.0) is the server reading that vocabulary
+ *    against the snapshot the documents were written with, and answering in
+ *    the request's own language. The schema is the floor under it, for a
+ *    server too old to send captions and for a slug the answer omits.
+ *
+ *    Neither invents a label: a value nobody names renders as itself. A page
+ *    against a pre-0.4.0 server therefore behaves exactly as it did — the key
+ *    is absent, every option falls through to the schema, and nothing
+ *    crashes on the missing key.
  *
  * A slug the server SKIPPED (`facet_meta.skipped`, dropped at
  * `MAX_FACET_FIELDS`) is not counted at all. Its options carry `count: null`,
  * never `0` — "we did not count this" and "there are none" are different
  * sentences and the honest one has to survive to the screen.
+ *
+ * 3. **Not every counted slug is a FILTER.** The plan is built from the leaf
+ *    category's feature defs and the counter counts whatever is indexed, so a
+ *    live classified deployment answers with `imei: {"355971829187494": 1}`
+ *    and `video_file_url: {}` beside its brand and its condition. Neither is
+ *    something a person narrows by — one is unique per document, the other is
+ *    a URL — and on a 390px chip row a chip offering one IMEI with a count of
+ *    one pushes the chips that DO narrow off the screen. Which slugs can be
+ *    chipped is therefore decided from the category's own feature defs, by
+ *    value TYPE (see {@link FACETABLE_FEATURE_TYPES}), not by what came back.
  */
-import { featureConfig, featureName, featureType, formatFeatureValue } from "@stapel/attributes-react";
+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";
 
+/**
+ * Value types whose values are a BOUNDED OPTION SET — the only kind of
+ * feature a person can be offered as a filter.
+ *
+ * The list is not invented here: the ref/vocabulary-backed half is
+ * `@stapel/attributes-react`'s own `VOCABULARY_BACKED_TYPES` (the one place
+ * that knows which types are drawn from a vocabulary), and the rest are the
+ * select family plus `bool`. Everything else a category can declare — a
+ * `string`, an `int`, a `date`, a `hex_color`, a `group` — enumerates as many
+ * terms as there are documents, which is a list, not a choice.
+ *
+ * `int`/`float`/`convertible_unit` are absent here and present in
+ * `RANGE_FEATURE_TYPES` (`state/ranges.ts`): a number is narrowed with two
+ * bounds, not with a checkbox per value. They are not dropped from the panel,
+ * they are drawn by the other half of the model.
+ */
+export const FACETABLE_FEATURE_TYPES: readonly string[] = [
+  "bool",
+  "hierarchical_select",
+  ...VOCABULARY_BACKED_TYPES,
+  "select",
+];
+
+/**
+ * Can a person filter by the slug this feature def describes?
+ *
+ * **A missing feature def is not a "no".** `categoryFeatures` is an OPTIONAL
+ * slot and a whole deployment can run without it; a feature can also be
+ * retired between the write that indexed a value and the read that counts it.
+ * Answering "not facetable" for an absent def would blank the entire chip row
+ * for every host that never threaded the schema through — the same empty row
+ * this rule exists to fix, arrived at from the other side. So the schema can
+ * only ever REMOVE a chip it names and disowns; silence removes nothing.
+ *
+ * The same reasoning covers a def with no `config.type` at all: an untyped
+ * feature is a def that says nothing, and nothing is not a verdict.
+ */
+export function isFacetableFeature(feature: FeatureDef | undefined): boolean {
+  if (feature === undefined) return true;
+  const type = featureType(feature);
+  if (type === undefined) return true;
+  return FACETABLE_FEATURE_TYPES.includes(type);
+}
+
 /** One value of one facet. */
 export interface FacetOption {
   readonly value: string;
@@ -59,6 +132,33 @@ export interface BuildFacetGroupsInput {
   readonly state: SearchQueryState;
   /** The category's feature schema, for labels and option order. */
   readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * The envelope's `facet_labels` (stapel-search 0.4.0+, vocabulary-backed
+   * from 0.6.0): `{slug: {translatable, values: {value: caption}}}`.
+   *
+   * The PRIMARY caption source, above `categoryFeatures`. Two reasons, and
+   * the second is the one that cannot be worked around:
+   *
+   *  - it is always there. The schema slot is optional and a live classified
+   *    board never filled it, so its buyers read "Condition: **b-u**" and
+   *    "Listing kind: **prodayu-svoe**" on the SERP and in the filter chips.
+   *  - it is the only source that RESOLVED anything. A `ref_select`'s config
+   *    carries an `optionsRef` pointer and no option table, so a host that
+   *    threads the entire schema through still has nothing to print for
+   *    `apple` or `chernyy`. The server read that vocabulary against the
+   *    snapshot the documents were written with.
+   *
+   * 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>> }
+    >
+  >;
   /** Translator for label keys. */
   readonly t?: (key: string) => string;
   /** BCP-47 tag, forwarded to `formatFeatureValue` for `date` options. */
@@ -71,6 +171,26 @@ function translate(t: ((key: string) => string) | undefined, key: string): strin
   return resolved.length > 0 ? resolved : key;
 }
 
+/**
+ * The caption the ANSWER carries for one option, or `undefined`.
+ *
+ * `translatable` is the server saying whether `values` holds translation
+ * KEYS or literal captions, and it has to be said rather than sniffed:
+ * `b.apple` and a rendered caption are both strings, and guessing wrong prints either a
+ * dotted key or an untranslated word at a buyer.
+ */
+function serverLabel(
+  labels: BuildFacetGroupsInput["facetLabels"],
+  slug: string,
+  value: string,
+  t: ((key: string) => string) | undefined
+): string | undefined {
+  const entry = labels?.[slug];
+  const caption = entry?.values[value];
+  if (caption === undefined || caption.length === 0) return undefined;
+  return entry?.translatable === true ? translate(t, caption) : caption;
+}
+
 /**
  * The declared option ORDER for a closed set, if the schema declares one.
  *
@@ -95,6 +215,34 @@ function declaredOptionValues(feature: FeatureDef | undefined): readonly string[
   return out;
 }
 
+/**
+ * One option's caption: the ANSWER, then the schema, then the raw value.
+ *
+ * The answer leads because it is the source that always exists and the only
+ * one that can name a vocabulary-backed value at all: a `ref_select`'s config
+ * is a POINTER (`optionsRef`), so a host who threaded the whole schema through
+ * still has nothing to print for `apple`. The server read that vocabulary
+ * against the snapshot the documents carry and answered in the request's own
+ * language, which is a strictly better-informed caption than the option table
+ * the schema may or may not hold.
+ *
+ * The schema is the floor: a server too old to send `facet_labels`, a slug the
+ * answer omits, a value the vocabulary has since dropped. Below both, the raw
+ * value — never a blank, and never a guess.
+ */
+function resolveLabel(
+  input: BuildFacetGroupsInput,
+  feature: FeatureDef | undefined,
+  slug: string,
+  value: string,
+  labelOptions: { t?: (key: string) => string; locale?: string }
+): string {
+  return (
+    serverLabel(input.facetLabels, slug, value, input.t) ??
+    facetOptionLabel(feature, value, labelOptions)
+  );
+}
+
 /**
  * A facet value as a person reads it, through
  * `@stapel/attributes-react`'s `formatFeatureValue` — the same formatter the
@@ -156,6 +304,13 @@ export function facetOptionLabel(
  * person has filtered on — the last one matters: a filter whose slug fell out
  * of the plan must stay visible, or it becomes a constraint with no control to
  * remove it.
+ *
+ * A slug the category schema names and types as something no one can choose
+ * from (see {@link isFacetableFeature}) produces no group at all — not an
+ * empty one, because an empty group is still a heading in the panel and still
+ * a chip in the row. The APPLIED-filter clause outranks the type rule: a
+ * constraint the URL carries always gets its control back, whatever the schema
+ * now says about it, or a person is left holding a filter they cannot clear.
  */
 export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGroup[] {
   const bySlug = new Map<string, FeatureDef>();
@@ -171,6 +326,10 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
   ]) {
     if (seen.has(slug)) continue;
     seen.add(slug);
+    // Applied first, type second — in that order, so an `imei` somebody
+    // somehow got into a link keeps the control that removes it.
+    const applied = (input.state.filters[slug] ?? []).length > 0;
+    if (!applied && !isFacetableFeature(bySlug.get(slug))) continue;
     slugs.push(slug);
   }
 
@@ -180,7 +339,15 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
     const counted = !skipped.has(slug) && slug in input.facets;
     const selected = input.state.filters[slug] ?? [];
 
-    const declared = declaredOptionValues(feature);
+    // The authored option order, from whichever copy of the category config
+    // this page has. An authored list reshuffled by count is a size chart
+    // that moves on every click, and until 0.11 a host that passed no schema
+    // got exactly that.
+    const fromSchema = declaredOptionValues(feature);
+    const declared =
+      fromSchema.length > 0
+        ? fromSchema
+        : Object.keys(input.facetLabels?.[slug]?.values ?? {});
     const values: string[] = [];
     const push = (value: string): void => {
       if (!values.includes(value)) values.push(value);
@@ -211,7 +378,12 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
       options: values.map((value) => ({
         value,
         count: counted ? (counts[value] ?? 0) : null,
-        label: facetOptionLabel(feature, value, labelOptions),
+        // 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),
         selected: selected.includes(value),
       })),
     };

package/src/state/ranges.ts

@@ -6,13 +6,23 @@
  * the panel only knew how to draw checkboxes. This module is the missing half:
  * which slugs a range row exists for, and what the row is called.
  *
- * ── Where a range row comes from, and why it is not the response ───────────
+ * ── Where a range row comes from ──────────────────────────────────────────
  *
- * A facet answer (`facets: {slug: {value: count}}`) enumerates DISCRETE values;
- * a range is not enumerable and the server never sends one. So the rows come
- * from the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
- * checkboxes their labels — filtered to the numeric value types, plus every
- * slug the URL already carries a range for.
+ * A facet answer (`facets: {slug: {value: count}}`) enumerates DISCRETE
+ * values; a range is not enumerable and no bucket is ever sent for one. So
+ * the rows come from two places:
+ *
+ *  - the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
+ *    checkboxes their labels — filtered to the numeric value types;
+ *  - the ANSWER's `facet_meta.core_ranges` (stapel-search 0.4.0+), which
+ *    names the range slugs addressing a COLUMN of the document rather than
+ *    an attribute. `price` is the shipped one, and it is why this module
+ *    exists at all: a live classified board offered seven numeric ranges,
+ *    every one of them a shipping or wholesale input, and no price — because
+ *    price is not a category feature anywhere, and a row was only ever drawn
+ *    for a feature.
+ *
+ * Plus every slug the URL already carries a range for.
  *
  * That last clause is the same rule `buildFacetGroups` follows for a filtered
  * slug that fell out of the plan: a constraint that is ACTIVE must always have
@@ -59,11 +69,50 @@ export interface RangeGroup {
   readonly step: number | undefined;
   /** Whether the URL currently constrains this slug. */
   readonly active: boolean;
+  /**
+   * `true` when the axis is a CORE document column the server declared in
+   * `facet_meta.core_ranges` rather than a category feature. Price is the
+   * shipped one. A core axis is drawn first and is never absent because a
+   * category forgot to declare an attribute for it.
+   */
+  readonly core: boolean;
+  /**
+   * ISO 4217 code when the row is money, so the control can read as money
+   * instead of as a bare integer. Only ever set on a core axis: an attribute
+   * carries a `postfix`, not a currency.
+   */
+  readonly currency: string | undefined;
+}
+
+/**
+ * i18n key for a core axis's own name.
+ *
+ * A core axis has no FeatureDef and therefore no `name` to translate. The
+ * label is this package's, because the axis is this package's.
+ */
+export function coreRangeLabelKey(slug: string): string {
+  return `search.range.${slug}`;
 }
 
 export interface BuildRangeGroupsInput {
   readonly state: SearchQueryState;
   readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * `facet_meta.core_ranges` — range slugs that address a column of the
+   * document rather than an attribute (stapel-search 0.4.0+).
+   *
+   * It comes from the ANSWER on purpose. A live classified board offered
+   * seven numeric ranges — parcel weight, length, height, width, packing
+   * quantity, minimum-order quantity, battery condition — and no price,
+   * because a row was only ever drawn for a category feature and price is a
+   * column of the listing. Hardcoding `"price"` here would have fixed that
+   * board and broken the next one, where `r.price` still answers zero
+   * because the server predates the axis. So the server says which axes it
+   * can actually serve, and this list is empty against an older one.
+   */
+  readonly coreRanges?: readonly string[];
+  /** ISO 4217 code for the money axes, when the surface knows one. */
+  readonly currency?: string;
   /** Translator for label keys (the schema's `name` is often one). */
   readonly t?: (key: string) => string;
 }
@@ -89,9 +138,15 @@ export function isRangeFeature(feature: FeatureDef): boolean {
 }
 
 /**
- * The range rows for the current search: every numeric feature of the
- * category, in the schema's own order, plus any slug the URL constrains that
- * the schema does not explain.
+ * The range rows for the current search, in the order they should be read:
+ * the CORE axes the answer declares, then every numeric feature of the
+ * category in the schema's own order, then any slug the URL constrains that
+ * neither explains.
+ *
+ * Core first is not cosmetic. On the board this was measured against, the
+ * seven numeric attributes a phone category happens to declare are all
+ * shipping and wholesale inputs; the one number a phone buyer narrows by is
+ * the price, and it belongs above them.
  */
 export function buildRangeGroups(
   input: BuildRangeGroupsInput
@@ -99,30 +154,45 @@ export function buildRangeGroups(
   const bySlug = new Map<string, FeatureDef>();
   for (const feature of input.categoryFeatures ?? []) bySlug.set(feature.slug, feature);
 
-  const slugs: string[] = [];
+  const core = new Set(input.coreRanges ?? []);
+  const slugs: string[] = [...core];
   for (const feature of input.categoryFeatures ?? []) {
-    if (isRangeFeature(feature)) slugs.push(feature.slug);
+    // A core slug shadows a same-named attribute — which is exactly what the
+    // server does with it (`index_schema.CORE_RANGE_FIELDS` reserves the
+    // slug), so drawing both would put two controls over one filter.
+    if (isRangeFeature(feature) && !core.has(feature.slug)) slugs.push(feature.slug);
   }
   for (const slug of Object.keys(input.state.ranges)) {
     if (!slugs.includes(slug)) slugs.push(slug);
   }
 
   return slugs.map((slug) => {
-    const feature = bySlug.get(slug);
+    const isCore = core.has(slug);
+    const feature = isCore ? undefined : bySlug.get(slug);
     const config = feature === undefined ? {} : featureConfig(feature);
     const applied: SearchRange | undefined = input.state.ranges[slug];
     return {
       slug,
-      label:
-        feature === undefined ? slug : translate(input.t, featureName(feature)),
+      label: isCore
+        ? translate(input.t, coreRangeLabelKey(slug))
+        : feature === undefined
+          ? slug
+          : translate(input.t, featureName(feature)),
       feature,
       from: applied?.from,
       to: applied?.to,
       min: num(config["min"]),
       max: num(config["max"]),
-      unit: str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"]),
+      // A core money axis carries a CURRENCY, not a unit suffix: "₽" is
+      // formatted from the code for the reader's locale, a unit suffix is a literal
+      // the category author typed.
+      unit: isCore
+        ? undefined
+        : (str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"])),
       step: feature !== undefined && featureType(feature) === "int" ? 1 : undefined,
       active: applied !== undefined,
+      core: isCore,
+      currency: isCore ? str(input.currency) : undefined,
     };
   });
 }