@stapel/search-react 0.29.1 → 0.31.0

package/src/state/ranges.ts

@@ -10,10 +10,20 @@
  *
  * 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 rows come from three places:
  *
+ *  - the ANSWER's `facet_meta.ranges` (stapel-search 0.14.7+) — `{slug:
+ *    {min, max}}` for every axis this page has NUMBERS behind, measured with
+ *    the range filters removed and uncapped by `MAX_FACET_FIELDS`. When the
+ *    answer reports it, it is the authority on which attribute axes exist and
+ *    where their ends are: the schema says an axis COULD be numeric, and this
+ *    says it IS, on these documents. It reaches axes the schema's own type
+ *    cannot — a vocabulary-backed `year`, a `floor`, a `doors` are CHOICES in
+ *    the catalogue and from/to's to a buyer, and both are served.
  *  - the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
- *    checkboxes their labels — filtered to the numeric value types;
+ *    checkboxes their labels — filtered to the numeric value types. It is the
+ *    FALLBACK, and the only source against a server that reports no `ranges`
+ *    (older, or an engine that listed `facet_ranges` in `degraded[]`).
  *  - 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
@@ -37,7 +47,11 @@
  */
 import { featureConfig, featureName, featureType } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
-import type { SearchQueryState, SearchRange } from "../api/types.js";
+import type {
+  FacetRangesMap,
+  SearchQueryState,
+  SearchRange,
+} from "../api/types.js";
 
 /**
  * Value types a numeric range row is drawn for (`config.type`, the
@@ -60,9 +74,19 @@ export interface RangeGroup {
    * never promised a number, and re-formatting one would rewrite the link). */
   readonly from: string | undefined;
   readonly to: string | undefined;
-  /** Bounds the schema declares, for the input's own limits. */
+  /** The axis's ends: the ANSWER's measured bounds when it reported any for
+   * this slug, the schema's declared ones otherwise. */
   readonly min: number | undefined;
   readonly max: number | undefined;
+  /**
+   * `true` when {@link min}/{@link max} were MEASURED over this answer
+   * (`facet_meta.ranges`) rather than declared by the schema.
+   *
+   * The difference is what a picker may be drawn from: a catalogue's
+   * `1900..2027` is what a year could be, and `2015..2020` is what this page
+   * has. Never set on a core axis — see {@link BuildRangeGroupsInput.ranges}.
+   */
+  readonly measured: boolean;
   /** Unit suffix the schema declares (`postfix`, or a convertible unit). */
   readonly unit: string | undefined;
   /** `1` for an integer feature — a whole-number input for a whole number. */
@@ -81,8 +105,10 @@ export interface RangeGroup {
    * to pick from — `undefined` for every other axis, including price.
    *
    * A year is not a number a person types, it is one of a hundred-odd values,
-   * and the reference classified draws it as two pickers. `min`/`max` from
-   * the schema (`year: 1900..2027` on a live cars leaf) bound the list;
+   * and the reference classified draws it as two pickers. {@link min}/{@link
+   * max} bound the list — the answer's measured ends when it reported any
+   * (`year: 1990..2024` over these documents), the schema's declared ones
+   * otherwise (`year: 1900..2027` on a live cars leaf);
    * {@link RANGE_PICKER_MAX_VALUES} is where a picker stops being one and
    * becomes a scroll with a search box in it, at which point two typed fields
    * are the better control. Descending, because the busy end of a bounded
@@ -124,6 +150,31 @@ export interface BuildRangeGroupsInput {
    * can actually serve, and this list is empty against an older one.
    */
   readonly coreRanges?: readonly string[];
+  /**
+   * `facet_meta.ranges` — the axes this ANSWER measured, and their ends
+   * (stapel-search 0.14.7+).
+   *
+   * Two jobs, and the second is the one the schema cannot do:
+   *  - BOUNDS. `min`/`max` come from here when the axis is in it, and from
+   *    the schema's `config` otherwise. A catalogue's `1900..2027` is what a
+   *    year COULD be; `2015..2020` is what this page has.
+   *  - EXISTENCE. An axis the schema types as a CHOICE — a vocabulary-backed
+   *    `year`, a `floor`, a `doors` — is a from/to to a buyer, and the server
+   *    now says so by measuring it. Reported axes get a row whatever the
+   *    schema calls them.
+   *
+   * `undefined` means the server said nothing: it predates 0.14.7, or its
+   * engine has no `ranges` verb and listed `facet_ranges` in `degraded[]`.
+   * The schema's bounds are the fallback then — never an empty rail, which
+   * would read as "this category has no numbers".
+   *
+   * A CORE axis is left alone by it. The price field is not clamped to the
+   * corpus's current ends: those ends move with every other filter, and an
+   * input that refuses the number a person meant to type is worse than an
+   * unbounded one. The measured price is still on the envelope for a host
+   * that wants to draw a histogram over it.
+   */
+  readonly ranges?: FacetRangesMap;
   /** 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). */
@@ -154,6 +205,34 @@ function translate(t: ((key: string) => string) | undefined, key: string): strin
  */
 export const RANGE_PICKER_MAX_VALUES = 300;
 
+/**
+ * Is this axis a WHOLE-NUMBER one — the question both the picker and the
+ * input's step ask?
+ *
+ * The schema answers it for a typed feature (`int`, and never `float` or a
+ * convertible unit, whose values are 1.4 litres). For an axis the schema
+ * types as a CHOICE, or does not describe at all, the ANSWER answers it: the
+ * server measured two ends over the real documents, and whole ends over a
+ * vocabulary of numeric codes is what a `year` or a `floor` is.
+ */
+function isIntegerAxis(
+  feature: FeatureDef | undefined,
+  min: number | undefined,
+  max: number | undefined,
+  measured: boolean
+): boolean {
+  const type = feature === undefined ? undefined : featureType(feature);
+  if (type === "int") return true;
+  if (type === "float" || type === "convertible_unit") return false;
+  return (
+    measured &&
+    min !== undefined &&
+    max !== undefined &&
+    Number.isInteger(min) &&
+    Number.isInteger(max)
+  );
+}
+
 /**
  * The value list for a bounded integer axis, or `undefined`.
  *
@@ -163,10 +242,10 @@ export const RANGE_PICKER_MAX_VALUES = 300;
 function pickerValues(
   feature: FeatureDef | undefined,
   min: number | undefined,
-  max: number | undefined
+  max: number | undefined,
+  measured: boolean
 ): readonly number[] | undefined {
-  if (feature === undefined) return undefined;
-  if (featureType(feature) !== "int") return undefined;
+  if (!isIntegerAxis(feature, min, max, measured)) return undefined;
   if (min === undefined || max === undefined) return undefined;
   if (!Number.isInteger(min) || !Number.isInteger(max)) return undefined;
   const span = max - min + 1;
@@ -198,12 +277,24 @@ export function buildRangeGroups(
   for (const feature of input.categoryFeatures ?? []) bySlug.set(feature.slug, feature);
 
   const core = new Set(input.coreRanges ?? []);
+  const bounds = input.ranges;
+  const reported = new Set(Object.keys(bounds ?? {}));
   const slugs: string[] = [...core];
   for (const feature of input.categoryFeatures ?? []) {
     // 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);
+    if (core.has(feature.slug)) continue;
+    // The schema's own numeric types, PLUS anything this answer measured: a
+    // vocabulary-backed `year` is a choice in the catalogue and a from/to on
+    // the page, and the server measuring it is the fact that settles it.
+    // Schema ORDER either way, so an axis does not move when it is measured.
+    if (isRangeFeature(feature) || reported.has(feature.slug)) slugs.push(feature.slug);
+  }
+  // Measured axes the schema never mentioned — a host that hands in no
+  // `categoryFeatures` still gets its rows, labelled by slug.
+  for (const slug of reported) {
+    if (!slugs.includes(slug)) slugs.push(slug);
   }
   for (const slug of Object.keys(input.state.ranges)) {
     if (!slugs.includes(slug)) slugs.push(slug);
@@ -214,6 +305,12 @@ export function buildRangeGroups(
     const feature = isCore ? undefined : bySlug.get(slug);
     const config = feature === undefined ? {} : featureConfig(feature);
     const applied: SearchRange | undefined = input.state.ranges[slug];
+    // Measured ends win over declared ones, on an attribute axis only — see
+    // `BuildRangeGroupsInput.ranges` for why the price input keeps its own.
+    const axis = isCore ? undefined : bounds?.[slug];
+    const measured = axis !== undefined;
+    const min = measured ? axis.min : num(config["min"]);
+    const max = measured ? axis.max : num(config["max"]);
     return {
       slug,
       label: isCore
@@ -224,16 +321,17 @@ export function buildRangeGroups(
       feature,
       from: applied?.from,
       to: applied?.to,
-      min: num(config["min"]),
-      max: num(config["max"]),
+      min,
+      max,
+      measured,
       // 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,
-      picker: isCore ? undefined : pickerValues(feature, num(config["min"]), num(config["max"])),
+      step: !isCore && isIntegerAxis(feature, min, max, measured) ? 1 : undefined,
+      picker: isCore ? undefined : pickerValues(feature, min, max, measured),
       active: applied !== undefined,
       core: isCore,
       currency: isCore ? str(input.currency) : undefined,