@stapel/search-react 0.10.0 → 0.11.0

package/src/headless/FacetPanel.tsx

@@ -31,6 +31,22 @@ export interface FacetPanelBag {
   readonly skipped: readonly string[];
   /** Slugs that WERE counted. */
   readonly counted: readonly string[];
+  /**
+   * Range slugs the server declared as CORE document columns
+   * (`facet_meta.core_ranges`, stapel-search 0.4.0+) — `price` on a
+   * classified board. They are not part of the category plan and are not
+   * counted; they are axes the panel may offer unconditionally, and they
+   * come from the answer so that a panel never draws a control over a
+   * filter the deployed server would answer zero for.
+   */
+  readonly coreRanges: readonly string[];
+  /**
+   * ISO 4217 code of the corpus, read off the first card of the answer, so
+   * a money range reads as money without the host wiring anything. The
+   * cards already carry it — `SearchResultCard` formats prices from the
+   * same field.
+   */
+  readonly currency: string | undefined;
   /** Size of the largest counted set — the number `approximate` is about. */
   readonly candidates: number;
   /** Facet values + ranges + geo currently applied. */
@@ -47,6 +63,7 @@ const EMPTY_META: FacetMeta = {
   candidates: 0,
   counted: [],
   skipped: [],
+  core_ranges: [],
 };
 
 /**
@@ -115,6 +132,7 @@ export function useFacetPanel(props: {
     buildFacetGroups({
       facets: data.facets,
       meta: data.facet_meta,
+      facetLabels: data.facet_labels,
       state: searchState,
       ...(props.categoryFeatures !== undefined
         ? { categoryFeatures: props.categoryFeatures }
@@ -129,6 +147,12 @@ export function useFacetPanel(props: {
     approximate: meta.approximate,
     skipped: meta.skipped,
     counted: meta.counted,
+    coreRanges: meta.core_ranges ?? [],
+    currency:
+      envelope.status === "ready"
+        ? envelope.data.items.find((item) => typeof item.card?.["currency"] === "string")
+            ?.card?.["currency"] as string | undefined
+        : undefined,
     candidates: meta.candidates,
     activeFilters,
     toggle: toggleFilter,

package/src/i18n/es.ts

@@ -72,6 +72,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.not_counted": "sin contar",
   "search.facets.drill_down_hint":
     "Cada recuento es lo que obtendrías eligiendo ese valor en lugar del actual.",
+  "search.range.price": "Precio",
   "search.facets.range_from": "Desde",
   "search.facets.range_to": "Hasta",
   "search.facets.range_apply": "Aplicar",

package/src/i18n/keys.ts

@@ -103,6 +103,9 @@ export const SEARCH_I18N_KEYS = {
   facetsRangeToAria: "search.facets.range_to_aria",
   /** The reason "Apply" is off: the range reads backwards. */
   facetsRangeInvalid: "search.facets.range_invalid",
+  /** A CORE range axis has no FeatureDef and so no `name` to translate.
+   * `search.range.<slug>`; `price` is the one stapel-search ships. */
+  rangePrice: "search.range.price",
   /** The fold on a long facet group: "Show all (46)". The number is in
    * brackets and not a counted noun, so this is one message and not a plural
    * family — "(1)" never renders, because a group is only folded when the
@@ -299,6 +302,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.not_counted": "not counted",
   "search.facets.drill_down_hint":
     "Each count is what you would get by choosing that value instead of the one you have.",
+  "search.range.price": "Price",
   "search.facets.range_from": "From",
   "search.facets.range_to": "To",
   "search.facets.range_apply": "Apply",

package/src/i18n/ru.ts

@@ -95,6 +95,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.not_counted": "не посчитано",
   "search.facets.drill_down_hint":
     "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",
+  "search.range.price": "Цена",
   "search.facets.range_from": "От",
   "search.facets.range_to": "До",
   "search.facets.range_apply": "Применить",

package/src/index.ts

@@ -89,11 +89,16 @@ export type {
 export {
   countIsEstimate,
   countKind,
+  degradationAudience,
   degradationMessageKey,
   isCountNuanceOnly,
   parseDegradations,
+  readerFacing,
+} from "./state/degradations.js";
+export type {
+  SearchCountKind,
+  SearchDegradationAudience,
 } from "./state/degradations.js";
-export type { SearchCountKind } from "./state/degradations.js";
 
 export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
 export type {
@@ -105,6 +110,7 @@ export type {
 export {
   RANGE_FEATURE_TYPES,
   buildRangeGroups,
+  coreRangeLabelKey,
   isRangeFeature,
   isRangeUsable,
 } from "./state/ranges.js";

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,12 +8,20 @@
  *    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 come from two places, in that order.** The category's
+ *    feature schema — `categoryFeatures`, the second slot-seam of the pair,
+ *    filled by the container from `categories-react` (spec §6.2 item 2) —
+ *    and, under it, the answer's own `facet_labels` (stapel-search 0.4.0+).
+ *
+ *    Until 0.4.0 the server sent `{value: count}` and nothing else, on the
+ *    reasoning that the container has the schema anyway. That reasoning had
+ *    a hole the size of a marketplace: the slot is OPTIONAL, a live
+ *    classified board never filled it, and its buyers read "Condition:
+ *    **b-u**", "Listing kind: **prodayu-svoe**", "Screen condition:
+ *    **bez-defektov**" on the SERP and in the filter chips. The schema still
+ *    wins where it resolves — the client fetched it with its own
+ *    `Accept-Language` — and the answer's captions are the floor beneath it.
+ *    Neither invents a label: a value nobody names renders as itself.
  *
  * A slug the server SKIPPED (`facet_meta.skipped`, dropped at
  * `MAX_FACET_FIELDS`) is not counted at all. Its options carry `count: null`,
@@ -59,6 +67,31 @@ 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+):
+   * `{slug: {translatable, values: {value: caption}}}`.
+   *
+   * The FLOOR under `categoryFeatures`, not a replacement for it. Both read
+   * the same category config, but they read it differently: the client
+   * fetches `GET /categories/{id}/features/` with its own `Accept-Language`,
+   * so a host that threaded the schema through has the better-localized
+   * copy and keeps it. What the answer's captions fix is the case where
+   * there is no other copy at all — `categoryFeatures` is an OPTIONAL slot,
+   * a live classified board never filled it, and its buyers read
+   * "Condition: **b-u**" and "Listing kind: **prodayu-svoe**" on the SERP and in the
+   * filter chips. A caption that arrives with the counts cannot be
+   * forgotten by a host.
+   *
+   * A slug neither side captions (a vocabulary-backed one, whose level lives
+   * outside the category schema) falls through to the raw value. 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 +104,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 +148,28 @@ function declaredOptionValues(feature: FeatureDef | undefined): readonly string[
   return out;
 }
 
+/**
+ * One option's caption: schema, then answer, then the raw value.
+ *
+ * Order matters and is deliberate. Both sources are the same category
+ * config, but the client fetched its copy with its own `Accept-Language`, so
+ * where the host threaded a schema through and it names the value, that is
+ * the better-localized answer. Where it does not — no schema, a slug the
+ * schema omits, a value added since — the server's caption is what stops
+ * `b-u` reaching a buyer.
+ */
+function resolveLabel(
+  input: BuildFacetGroupsInput,
+  feature: FeatureDef | undefined,
+  slug: string,
+  value: string,
+  labelOptions: { t?: (key: string) => string; locale?: string }
+): string {
+  const viaSchema = facetOptionLabel(feature, value, labelOptions);
+  if (feature !== undefined && viaSchema !== value) return viaSchema;
+  return serverLabel(input.facetLabels, slug, value, input.t) ?? viaSchema;
+}
+
 /**
  * A facet value as a person reads it, through
  * `@stapel/attributes-react`'s `formatFeatureValue` — the same formatter the
@@ -180,7 +255,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 +294,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,
     };
   });
 }