@stapel/search-react 0.31.0 → 0.32.0

package/src/state/panel.ts

@@ -0,0 +1,138 @@
+/**
+ * ONE panel, not two halves of one — the order a filter rail draws its facet
+ * groups and its numeric axes in.
+ *
+ * ── The defect this closes ────────────────────────────────────────────────
+ *
+ * The rail drew three blocks in a fixed sequence: the CORE ranges (price),
+ * then every facet group, then every attribute range. That sequence is a
+ * client's opinion about a catalogue it has never read, and on a live cars
+ * leaf it put "Year" — a measurement the category authors second,
+ * right after the make — below forty checkbox groups, while "Price" sat above
+ * a make picker the schema puts first. A host asking for
+ * `partition → make → price → year` could pin the two GROUPS and had no way
+ * to say where the two RANGES went, because the two halves were ordered by
+ * different code and never compared.
+ *
+ * stapel-search 0.16.0 ends the argument by numbering both halves in ONE
+ * sequence: `facet_labels[<slug>].order` and `facet_meta.ranges[<slug>].order`
+ * are the same integer scale, assigned by the plan — core ranges first (they
+ * address a column every document in every corpus has), then the category's
+ * own schema order, mandatory first. Sorting both halves by that one key is
+ * all this module does.
+ *
+ * ── What happens when nobody numbered anything ────────────────────────────
+ *
+ * An older server states no `order` at all, and a row built from the CATEGORY
+ * SCHEMA alone never has one however new the server is. Those items keep the
+ * band order this pair has always used — core ranges, then the groups in the
+ * order the caller handed them (which is `orderFacetGroupsBySchema`'s), then
+ * the remaining measurements — and sit AFTER everything the plan did number,
+ * because a stated position is evidence and an assumed one is not.
+ *
+ * `pinned` outranks both. It is the host saying "this page is about make",
+ * and a page that has decided what it is about is not overruled by the
+ * category's own idea of a reading order.
+ */
+import type { FacetGroup } from "./facets.js";
+import type { RangeGroup } from "./ranges.js";
+
+/** One row of the panel: a bucket list, or a from/to picker. */
+export type PanelItem =
+  | { readonly kind: "group"; readonly slug: string; readonly group: FacetGroup }
+  | { readonly kind: "range"; readonly slug: string; readonly range: RangeGroup };
+
+export interface OrderPanelItemsInput {
+  /**
+   * The facet groups, already filtered to what is drawable and ordered the
+   * way the rail wants them — `orderFacetGroupsBySchema`'s output. Their
+   * relative order is preserved for every group the plan did not number.
+   */
+  readonly groups: readonly FacetGroup[];
+  /** The range rows, `buildRangeGroups`' output. */
+  readonly ranges: readonly RangeGroup[];
+  /**
+   * Slugs pinned above everything, in the order given — the axis a page has
+   * already decided is its subject. A slug matches whichever half carries it,
+   * so `["make", "price", "year"]` is one sequence over both.
+   */
+  readonly pinned?: readonly string[];
+}
+
+/**
+ * The panel's rows, in the one order they are read in.
+ *
+ * Three bands, and every one of them is stable — equal-ranked items keep the
+ * order they arrived in, so nothing reshuffles under a click:
+ *
+ *  1. `pinned`, in the order given.
+ *  2. everything the ANSWER numbered (`order`), ascending. Both halves share
+ *     the scale, so a group and a range can interleave inside it.
+ *  3. everything nobody numbered: core ranges, then groups, then attribute
+ *     ranges — the band order the rail shipped with, kept for exactly the case
+ *     it was invented for (a server or a row with no stated position).
+ */
+export function orderPanelItems(
+  input: OrderPanelItemsInput
+): readonly PanelItem[] {
+  const items: PanelItem[] = [
+    ...input.groups.map(
+      (group): PanelItem => ({ kind: "group", slug: group.slug, group })
+    ),
+    ...input.ranges.map(
+      (range): PanelItem => ({ kind: "range", slug: range.slug, range })
+    ),
+  ];
+
+  const pinnedIndex = new Map<string, number>();
+  (input.pinned ?? []).forEach((slug, index) => {
+    if (!pinnedIndex.has(slug)) pinnedIndex.set(slug, index);
+  });
+
+  const stated = (item: PanelItem): number | undefined =>
+    item.kind === "range" ? item.range.order : orderOf(item.group);
+
+  // The fallback band's own three tiers. A core axis first for the reason it
+  // has always been first: on a phones leaf every attribute range is parcel
+  // logistics and the one number a buyer narrows by is the price.
+  const fallbackTier = (item: PanelItem): number => {
+    if (item.kind === "range") return item.range.core ? 0 : 2;
+    return 1;
+  };
+
+  const decorated = items.map((item, index) => ({ item, index }));
+  decorated.sort((a, b) => {
+    const pinA = pinnedIndex.get(a.item.slug);
+    const pinB = pinnedIndex.get(b.item.slug);
+    if (pinA !== undefined || pinB !== undefined) {
+      if (pinA === undefined) return 1;
+      if (pinB === undefined) return -1;
+      if (pinA !== pinB) return pinA - pinB;
+      return a.index - b.index;
+    }
+    const orderA = stated(a.item);
+    const orderB = stated(b.item);
+    if (orderA !== undefined || orderB !== undefined) {
+      // A stated position beats an assumed one, so the unnumbered tail follows
+      // the plan rather than being interleaved into it by a guess.
+      if (orderA === undefined) return 1;
+      if (orderB === undefined) return -1;
+      if (orderA !== orderB) return orderA - orderB;
+      return a.index - b.index;
+    }
+    const tier = fallbackTier(a.item) - fallbackTier(b.item);
+    if (tier !== 0) return tier;
+    return a.index - b.index;
+  });
+  return decorated.map((entry) => entry.item);
+}
+
+/**
+ * A group's stated position, or `undefined`.
+ *
+ * `null` is the server's own "the plan has no place for this group" and reads
+ * exactly like an absent field — both mean "sort me with the rest".
+ */
+function orderOf(group: FacetGroup): number | undefined {
+  return typeof group.order === "number" ? group.order : undefined;
+}

package/src/state/ranges.ts

@@ -12,14 +12,19 @@
  * values; a range is not enumerable and no bucket is ever sent for one. So
  * 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 ANSWER's `facet_meta.ranges` (stapel-search 0.14.7+, a whole axis
+ *    rather than two numbers since 0.16.0) — `{slug: {min, max, label,
+ *    label_translatable, unit?, order}}` for every axis this page has NUMBERS
+ *    behind, measured with the range filters removed. When the answer reports
+ *    it, it is the authority on which attribute axes exist, where their ends
+ *    are, WHAT THEY ARE CALLED and where in the panel they sit: the schema
+ *    says an axis COULD be numeric, and this says it IS, on these documents,
+ *    under this name. 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 ANSWER's `facet_meta.withheld` (0.16.0), which is the same authority
+ *    used in the negative: an axis it names as a withheld `range` is one this
+ *    answer planned and declined to offer, and no schema row resurrects it.
  *  - the CATEGORY SCHEMA — the same `categoryFeatures` slot that gives the
  *    checkboxes their labels — filtered to the numeric value types. It is the
  *    FALLBACK, and the only source against a server that reports no `ranges`
@@ -49,9 +54,11 @@ import { featureConfig, featureName, featureType } from "@stapel/attributes-reac
 import type { FeatureDef } from "@stapel/attributes-react";
 import type {
   FacetRangesMap,
+  FacetWithheldAxis,
   SearchQueryState,
   SearchRange,
 } from "../api/types.js";
+import { withheldSlugs } from "../api/types.js";
 
 /**
  * Value types a numeric range row is drawn for (`config.type`, the
@@ -66,7 +73,13 @@ export const RANGE_FEATURE_TYPES: readonly string[] = [
 /** One `r.<slug>` row of the filter panel. */
 export interface RangeGroup {
   readonly slug: string;
-  /** The feature's display name (translated when it is a key), else the slug. */
+  /**
+   * What to write above the picker: the ANSWER's own caption first (0.16.0
+   * resolves it from the same definition a group heading comes from), the
+   * schema's display name next, this package's key for a core axis, and — only
+   * for a slug the URL constrains that none of them explain — the slug itself.
+   * {@link named} says which of those two worlds the row is in.
+   */
   readonly label: string;
   /** The schema entry behind the slug, when the host supplied one. */
   readonly feature: FeatureDef | undefined;
@@ -87,7 +100,10 @@ export interface RangeGroup {
    * has. Never set on a core axis — see {@link BuildRangeGroupsInput.ranges}.
    */
   readonly measured: boolean;
-  /** Unit suffix the schema declares (`postfix`, or a convertible unit). */
+  /** What the numbers are measured in: the ANSWER's `unit` (the definition's
+   * `postfix`, or the BASE unit of a convertible family) when it states one,
+   * the schema's own affixes otherwise. Absent, never `""`, on an axis nobody
+   * gave a unit — a price among them. */
   readonly unit: string | undefined;
   /** `1` for an integer feature — a whole-number input for a whole number. */
   readonly step: number | undefined;
@@ -121,6 +137,31 @@ export interface RangeGroup {
    * carries a `postfix`, not a currency.
    */
   readonly currency: string | undefined;
+  /**
+   * Where this axis sits in the ONE sequence the panel draws — the answer's
+   * `facet_meta.ranges[<slug>].order`, numbered together with the groups'
+   * `facet_labels[<slug>].order` (stapel-search 0.16.0+).
+   *
+   * `undefined` means the answer stated no position (an older server, an axis
+   * the plan has no place for, or a row that came from the schema alone), and
+   * a panel then falls back to the band order it has always used: core axes
+   * first, then the groups, then the rest of the measurements. See
+   * `orderPanelItems`.
+   */
+  readonly order: number | undefined;
+  /**
+   * `true` when {@link label} is a name SOMEBODY GAVE the axis — the answer's
+   * own caption, the schema's `FeatureDef.name`, or this package's key for a
+   * core axis — and `false` when it is the storage slug standing in for a name
+   * nobody has.
+   *
+   * A row is only ever unlabelled when the URL already constrains the slug: a
+   * constraint must keep the control that removes it, even one captioned
+   * `power_w`. Every other unnamed axis is dropped before it reaches a
+   * surface, which is the client half of the rule stapel-search 0.16.0 states
+   * on the wire by WITHHOLDING an axis it could not caption.
+   */
+  readonly named: boolean;
 }
 
 /**
@@ -175,6 +216,24 @@ export interface BuildRangeGroupsInput {
    * that wants to draw a histogram over it.
    */
   readonly ranges?: FacetRangesMap;
+  /**
+   * `facet_meta.withheld` — the axes the server planned and then did NOT
+   * offer (stapel-search 0.16.0+).
+   *
+   * Only the rows whose `axis` is `"range"` are read here, and reading them is
+   * not optional: an axis withheld for `coverage` describes three of fifty-two
+   * documents and an axis withheld as `unlabelled` has no caption anyone could
+   * print, and the server leaving it out of `ranges` is only half the
+   * statement — the CATEGORY SCHEMA still names the same slug, so a rail that
+   * ignored this list would draw from the schema exactly the row the answer
+   * just declined to offer.
+   *
+   * The one exemption is a slug the URL constrains. The server promises never
+   * to withhold one (that would leave a filter applied with no control to undo
+   * it) and this module keeps the row anyway if it ever does, for the same
+   * reason it keeps a row the schema cannot explain.
+   */
+  readonly withheld?: readonly FacetWithheldAxis[];
   /** 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). */
@@ -279,6 +338,9 @@ export function buildRangeGroups(
   const core = new Set(input.coreRanges ?? []);
   const bounds = input.ranges;
   const reported = new Set(Object.keys(bounds ?? {}));
+  // The axes this answer planned and declined to offer — sparse, or with no
+  // caption anyone could print. Dropped unless the URL constrains them.
+  const withheld = new Set(withheldSlugs(input.withheld, "range"));
   const slugs: string[] = [...core];
   for (const feature of input.categoryFeatures ?? []) {
     // A core slug shadows a same-named attribute — which is exactly what the
@@ -300,43 +362,92 @@ export function buildRangeGroups(
     if (!slugs.includes(slug)) slugs.push(slug);
   }
 
-  return slugs.map((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];
-    // 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
-        ? translate(input.t, coreRangeLabelKey(slug))
-        : feature === undefined
-          ? slug
-          : translate(input.t, featureName(feature)),
-      feature,
-      from: applied?.from,
-      to: applied?.to,
-      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: !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,
-    };
-  });
+  return slugs
+    .map((slug): RangeGroup => {
+      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];
+      // The ANSWER's row for the slug. Read for its caption on every axis
+      // including a core one — the server names `price` out of its own
+      // `CORE_RANGE_LABELS` — and for its BOUNDS on an attribute axis only:
+      // see `BuildRangeGroupsInput.ranges` for why the price input keeps its
+      // own ends.
+      const axis = bounds?.[slug];
+      const measured = !isCore && axis !== undefined;
+      const min = measured ? axis.min : num(config["min"]);
+      const max = measured ? axis.max : num(config["max"]);
+      // The caption, in the order of who is entitled to give one:
+      //  1. the ANSWER. `label` is resolved server-side from the same
+      //     definition a group heading comes from, it is present for a core
+      //     axis the client has no definition for, and it is the only source
+      //     a host that threaded no schema has at all.
+      //  2. the SCHEMA's own `name`, for a server too old to send one.
+      //  3. this package's key for a core axis, same reason as (2).
+      // and never the slug, which is storage. An axis none of the three name
+      // is dropped below.
+      const answered = str(axis?.label);
+      const named =
+        answered !== undefined || isCore || feature !== undefined;
+      const label =
+        answered !== undefined
+          ? // `label_translatable: false` is literal text the catalogue wrote
+            // and must not be looked up; absent means the server did not say,
+            // and a lookup that misses returns the string unchanged.
+            axis?.label_translatable === false
+            ? answered
+            : translate(input.t, answered)
+          : isCore
+            ? translate(input.t, coreRangeLabelKey(slug))
+            : feature === undefined
+              ? slug
+              : translate(input.t, featureName(feature));
+      return {
+        slug,
+        label,
+        named,
+        feature,
+        from: applied?.from,
+        to: applied?.to,
+        min,
+        max,
+        measured,
+        // The unit, same precedence and same reason: the answer resolved it
+        // off the definition (a `convertible_unit`'s BASE unit, which the
+        // client cannot work out from `unit_m`/`unit_i` alone), the schema's
+        // own affixes second. Translated, because the server states plainly
+        // that it never translates one and the string may be a key.
+        //
+        // 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(axis?.unit) !== undefined
+            ? translate(input.t, str(axis?.unit) ?? "")
+            : (str(config["postfix"]) ?? str(config["unit_m"]) ?? str(config["unit_i"])),
+        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,
+        order: typeof axis?.order === "number" ? axis.order : undefined,
+      };
+    })
+    .filter((group) => {
+      // A CONSTRAINT ALWAYS KEEPS ITS CONTROL. Everything below removes a row
+      // the reader has not used; a row they have is never one of them.
+      if (group.active) return true;
+      // The server planned this axis and declined to offer it — sparse, or
+      // unnameable. The schema still declares the same slug, so without this
+      // the rail would draw exactly the row the answer withheld.
+      if (withheld.has(group.slug)) return false;
+      // Nobody named it. A from/to picker captioned `kilometrage` is a control
+      // whose meaning a reader has to guess out of the numbers inside it,
+      // which is not a filter — the same judgement stapel-search 0.16.0 makes
+      // on the wire, made again here for the rows that come from the schema.
+      return group.named;
+    });
 }
 
 /**