@stapel/search-react 0.9.1 → 0.11.0

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/limits.ts

@@ -27,6 +27,29 @@ export const SEARCH_MAX_PAGE_SIZE = 100;
 /** `services.suggest` clamps `limit` into `1..25`. */
 export const SUGGEST_MAX_LIMIT = 25;
 
+/**
+ * The page a COUNT read asks for.
+ *
+ * There is no count-only endpoint (`SearchApi` is query/suggest/ranking), so
+ * `useSearchCount` rides the ordinary query and takes the total out of the
+ * envelope. One row is the smallest page the endpoint documents — `limit=0` is
+ * not a page size — and it is the difference between serializing one card
+ * nobody renders and serializing the default twenty-four.
+ */
+export const SEARCH_COUNT_PAGE_SIZE = 1;
+
+/**
+ * How long a composing panel has to stop changing before its count is asked
+ * for.
+ *
+ * Shorter than the search commit (350ms): a count follows discrete choices — a
+ * select, a chip, a range end — rather than keystrokes, and a button whose
+ * number arrives a third of a second after the choice reads as broken. Longer
+ * than zero: the read is a full query (see `SEARCH_COUNT_PAGE_SIZE`), so a
+ * person walking a select's options must not spend one search per option.
+ */
+export const SEARCH_COUNT_DEBOUNCE_MS = 250;
+
 /**
  * The shortest prefix worth asking the index about.
  *

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,
     };
   });
 }