@stapel/search-react 0.29.0 → 0.30.1

package/src/api/generated/schema.ts

@@ -229,6 +229,10 @@ export interface components {
             values: {
                 [key: string]: string;
             };
+            /** @description The vocabulary name this group's options come from, when the feature is `ref_select` (or any host type pointing at a vocabulary the same way). `null` for a group with an inline option set — a client that only sees this answer, with no leaf schema of its own (a branch page, a text query), still needs this to draw a vocabulary-backed axis as its picker rather than as a plain checkbox list. */
+            vocabulary: string | null;
+            /** @description The vocabulary level `vocabulary` resolves against. Present only alongside a non-null `vocabulary`. */
+            level?: string;
         };
         FacetMeta: {
             /** @description True when counts came from a sample because the candidate set exceeded FACET_CANDIDATE_CAP. */
@@ -242,6 +246,10 @@ export interface components {
             dropped_filters: string[];
             /** @description Range slugs that address a core document column rather than an attribute (`r.price`). Offer them as filters unconditionally: they exist for every document in every category, which is why they are not in the category's own plan. */
             core_ranges: string[];
+            /** @description `{slug: {min, max}}` — the low and high bound of every numeric axis that HAS a number on this page, core columns (`price`) and attributes (`year`, `mileage`, `engine_volume`) alike. What a from/to picker is drawn from: a range axis has no values to enumerate, so `facets` says nothing about it and a client without these two numbers either draws no picker or draws one over a guess. Measured with the range filters REMOVED, so the ends are the domain the picker can be widened back to and not the ends of its own selection. An axis absent here has no numbers behind it in this candidate set — which is a different fact from a bound of zero. Not capped by MAX_FACET_FIELDS: the budget governs counting, and every bound is one aggregate. Empty, with `facet_ranges` in `degraded[]`, on an engine that does not implement the optional `ranges` verb. */
+            ranges: {
+                [key: string]: unknown;
+            };
             /** @description Where the plan came from. `category` — the queried category's own authored schema. `evidence` — the categories the CANDIDATE SET actually contains, used when that schema did not fill MAX_FACET_FIELDS, which is every branch category and every text query (`categories.features` resolves own + ANCESTOR-inherited features, so a branch owns no axes; its leaves do). */
             plan: string;
             /** @description `{slug, coverage, candidates}` for groups that were counted and then withheld because they describe too little of the result set (FACET_MIN_COVERAGE). Present so a panel can say «3 filters apply to too few of these» instead of «no filters» — the second is false whenever this list is not empty. Only slugs the evidence plan borrowed from another category are ever here, and never one the reader has already filtered on. */
@@ -372,7 +380,7 @@ export interface components {
                     [key: string]: number;
                 };
             };
-            /** @description {slug: {label, label_translatable, url_key, translatable, values: {value: caption}}} — one entry for EVERY group in `facets`. `url_key` is the group's key in the address. `label` is the group's heading and is null when the definition has no name; `values` is empty for a slug whose options are not inline in the category schema and whose vocabulary resolved nothing, because this module will not invent a caption it has not read. */
+            /** @description {slug: {label, label_translatable, url_key, translatable, values: {value: caption}, vocabulary, level}} — one entry for EVERY group in `facets`. `url_key` is the group's key in the address. `label` is the group's heading and is null when the definition has no name; `values` is empty for a slug whose options are not inline in the category schema and whose vocabulary resolved nothing, because this module will not invent a caption it has not read. `vocabulary` names the vocabulary a `ref_select` axis reads its options from and is null for an inline `select` — the only way a client with no leaf schema of its own can tell the two apart. */
             facet_labels: {
                 [key: string]: components["schemas"]["FacetLabels"];
             };

package/src/api/types.ts

@@ -33,7 +33,7 @@ export type Schemas = components["schemas"];
  */
 export type FacetLabels = Omit<
   Schemas["FacetLabels"],
-  "label" | "label_translatable" | "url_key"
+  "label" | "label_translatable" | "url_key" | "vocabulary"
 > & {
   readonly label?: string | null;
   /**
@@ -79,6 +79,14 @@ export type FacetLabels = Omit<
    * category schema's own `optionsRef`, which a host that threaded no schema
    * does not have. Absent on every server that does not state it — absence
    * is not "inline", it is "unsaid", and the schema is asked next.
+   *
+   * WHY IT IS NOT THE GENERATED SHAPE: stapel-search 0.14.9 added it and
+   * declares it REQUIRED, and the announced contract is `>=0.14 <0.15` — a
+   * 0.14.0 server inside that range sends no `vocabulary` at all. Same
+   * treatment as `url_key` above: `Omit`ted from the generated member and
+   * re-declared optional here, because a type must not promise a field a
+   * server the pair says it supports does not send. `level` is generated
+   * optional already and is inherited unchanged.
    */
   readonly vocabulary?: string | null;
 };
@@ -125,6 +133,32 @@ export interface FacetCategoryCount {
   readonly count: number;
 }
 
+/**
+ * The two ENDS of one numeric axis, measured over this answer's candidate set
+ * with the range filters removed (stapel-search 0.14.7+).
+ *
+ * Numbers, not strings: a slider end is arithmetic a client does immediately,
+ * and a price re-parsed from a formatted string is a price that has already
+ * been rounded once.
+ */
+export interface FacetRangeBounds {
+  readonly min: number;
+  readonly max: number;
+}
+
+/**
+ * `facet_meta.ranges` — `{slug: {min, max}}` for every axis this answer has
+ * numbers behind, core columns and attribute axes in ONE report because one
+ * rail draws both.
+ *
+ * An axis ABSENT from the map has no numbers behind it on this page, which is
+ * a different fact from a bound of zero. The map itself absent is a different
+ * fact again: the server predates 0.14.7, or its engine has no `ranges` verb
+ * and said so as `facet_ranges` in `degraded[]`. The panel tells the
+ * three apart — see `state/ranges.ts`.
+ */
+export type FacetRangesMap = Readonly<Record<string, FacetRangeBounds>>;
+
 /**
  * The honesty block beside the counts: `approximate`, `candidates`,
  * `counted`, `skipped`, and (stapel-search 0.12.0+) where the facet plan came
@@ -134,14 +168,25 @@ export interface FacetCategoryCount {
  * `categories` as bare `object` arrays, so the generated members are
  * `{[key: string]: unknown}[]` — the two fields a panel has to read
  * field-by-field are the two it cannot. Both are corrected here to the
- * documented row shapes; nothing else about `FacetMeta` is hand-written.
+ * documented row shapes.
+ *
+ * `ranges` (stapel-search 0.14.7) is now GENERATED, and is corrected here for
+ * both of the reasons the two fields above are. The generator lost the row
+ * shape — `additionalProperties: {}` becomes `{[key: string]: unknown}`, so
+ * the map a slider reads two numbers out of arrives with no numbers in the
+ * type — and drf-spectacular declares it required while the announced
+ * contract is `>=0.14 <0.15`, inside which a 0.14.0..0.14.6 server measures
+ * no bounds at all. Optional is the deployment truth: absent means "this
+ * server does not measure bounds", and a required field would compile while
+ * reading `undefined` from a key the compiler swore was there.
  */
 export type FacetMeta = Omit<
   Schemas["FacetMeta"],
-  "withheld" | "categories"
+  "withheld" | "categories" | "ranges"
 > & {
   readonly withheld: readonly FacetWithheldGroup[];
   readonly categories: readonly FacetCategoryCount[];
+  readonly ranges?: FacetRangesMap;
 };
 
 /** `GET /suggest` 200, as the CURRENT generated schema describes it. */

package/src/default/FacetGroupControl.tsx

@@ -145,6 +145,63 @@ function singleChoice(feature: FeatureDef | undefined): boolean {
   return numberish(featureConfig(feature)["maxSelected"]) === 1;
 }
 
+/**
+ * Slugs a marketplace's own mapping conventionally normalizes an EITHER/OR
+ * axis to, whatever language the printed labels end up in — a scraped
+ * catalogue's own "condition" column, however it was captioned on the source
+ * site, becomes one `condition` slug upstream of this component, so the slug
+ * is the one part of a schemaless group that survives translation. `is_*`/
+ * `has_*` catches a bare boolean the same way.
+ */
+const EXCLUSIVE_AXIS_SLUGS: ReadonlySet<string> = new Set([
+  "condition",
+  "item_condition",
+  "product_condition",
+  "state",
+]);
+
+function looksLikeExclusiveAxisSlug(slug: string): boolean {
+  const normalized = slug.toLowerCase();
+  if (/^(is|has)_/.test(normalized)) return true;
+  return EXCLUSIVE_AXIS_SLUGS.has(normalized);
+}
+
+/**
+ * Does a SCHEMALESS group's evidence look like a closed EITHER/OR rather
+ * than an open list — "pick one of these two or three" rather than "tick any
+ * of these"?
+ *
+ * There is no authoritative answer to read: `facet_meta` reports `skipped`,
+ * `withheld`, `ranges`, `plan`, `categories` and nothing that marks an axis
+ * single-valued, so a group with no `feature` (no schema, no `maxSelected`)
+ * has no `single` hint to defer to today. Once the plan sends one, THIS
+ * FUNCTION IS THE PLACE TO PREFER IT over the guess below.
+ *
+ * Until then: 2–3 counted buckets under a slug that reads as a condition or
+ * a boolean ({@link looksLikeExclusiveAxisSlug}) draw as segmented pills, on
+ * the same reasoning `singleChoice` already applies to a typed def — a
+ * two-way "new/used" read as tick-any-of-these is the wrong control before
+ * the first click. Every other schemaless small group (`color`, `size`)
+ * stays checkboxes: nothing here says a person can only want one, and
+ * assuming so for every short option list would turn `color` into a radio
+ * button the moment nobody threaded its schema through.
+ *
+ * Stated honestly, this is a GUESS keyed on the slug alone — it will miss an
+ * axis mapped under a slug not in {@link EXCLUSIVE_AXIS_SLUGS} and it will
+ * fire wrongly if some catalogue really does mean "condition" as a
+ * multi-select. Both failures draw checkboxes for a true either/or or pills
+ * for a true multi-select respectively — a shape mismatch, not a filter that
+ * stops working, and one a real `facet_meta` hint replaces outright.
+ */
+function looksSingleChoiceByEvidence(group: FacetGroup): boolean {
+  if (group.feature !== undefined) return false;
+  if (!looksLikeExclusiveAxisSlug(group.slug)) return false;
+  const buckets = group.options.filter(
+    (option) => option.count !== null && option.count > 0
+  ).length;
+  return buckets >= 2 && buckets <= 3;
+}
+
 /**
  * Is this group a DICTIONARY — an axis whose values live in a vocabulary?
  *
@@ -201,6 +258,11 @@ export function isDictionaryFacet(group: FacetGroup): boolean {
  *  - and a dictionary is a dictionary before it is a checkbox list, because
  *    the checkbox list is the shape it was drawn as when nobody could pick a
  *    make.
+ *
+ * A group with NO schema falls to {@link looksSingleChoiceByEvidence} for the
+ * segmented/checkbox call, since `singleChoice` has no `feature` to read
+ * `maxSelected` off of — see that function for what it checks and why it is
+ * a documented guess, not a fact read off the wire.
  */
 export function facetGroupShape(group: FacetGroup): FacetGroupShape {
   const feature = group.feature;
@@ -208,7 +270,8 @@ export function facetGroupShape(group: FacetGroup): FacetGroupShape {
     return "nested";
   }
   if (isDictionaryFacet(group)) return "dictionary";
-  return singleChoice(feature) ? "segmented" : "checkbox";
+  if (singleChoice(feature) || looksSingleChoiceByEvidence(group)) return "segmented";
+  return "checkbox";
 }
 
 /**

package/src/default/FacetPanelPane.tsx

@@ -105,7 +105,7 @@ import { FacetGroupControl } from "./FacetGroupControl.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { LanguageSelect } from "./LanguageSelect.js";
-import { RangeFilterRow } from "./RangeFilterRow.js";
+import { RANGE_ROW_MIN_HEIGHT, RangeFilterRow, RangeRowSkeleton } from "./RangeFilterRow.js";
 import type { ThemeModeProp } from "./types.js";
 
 /**
@@ -579,6 +579,10 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               ? { categoryFeatures: props.categoryFeatures }
               : {}),
             coreRanges: bag.coreRanges,
+            // The measured ends, and the axes the schema types as choices —
+            // a vocabulary-backed year is a from/to here because the answer
+            // says it has numbers behind it (stapel-search 0.14.7).
+            ...(bag.ranges !== undefined ? { ranges: bag.ranges } : {}),
             ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
             t,
           });
@@ -589,6 +593,11 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
           // classified catalogue means parcel weight and wholesale packing.
           const coreRanges = ranges.filter((group) => group.core);
           const attributeRanges = ranges.filter((group) => !group.core);
+          // How many rows the block reserves while the answer is in flight:
+          // what this category was last MEASURED to have, else what the
+          // schema declares. See the reservation comment below.
+          const reservedAxes =
+            bag.reservedRangeAxes?.length ?? attributeRanges.length;
           // Is there anything on this rail besides the facet groups? A price
           // row, an applied location, or the partition slot all make "this
           // search offers no filters" false even when the group list itself
@@ -876,23 +885,66 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 phone). It is a real filter for the person who wants it, so it
                 is not deleted; it is ranked where the chip row already ranks
                 it. */}
-            {attributeRanges.length > 0 && (
+            {/* The reservation, not just the rows (D361).
+                On a live category feed at 1536px this block's arrival was a
+                53px jump: `attributeRanges` draws from the CATEGORY SCHEMA
+                (`props.categoryFeatures`), and a host that fetches the
+                schema alongside the search answer had nothing here at all
+                until both landed — no host slot reserved the box, so the
+                rail grew under the reader's eye the instant it did.
+
+                Two things can be unknown at first paint, and each gets its
+                own reservation:
+                 - the SCHEMA itself (`categoryFeatures` undefined) — the
+                   axis count is unknown, so the fallback is one row's floor,
+                   a guess rather than nothing;
+                 - the ANSWER (`bag.state` not yet "ready") with a known
+                   schema — the axis COUNT is already certain from the
+                   schema, so the rail draws that many skeleton rows, each
+                   `RANGE_ROW_MIN_HEIGHT` tall like the real one it will
+                   become. Same count in both arms, so the swap from
+                   skeleton to `<RangeFilterRow>` costs no further height.
+
+                And the schema is only the FIRST guess at that count. Since
+                stapel-search 0.14.7 the answer measures the axes that have
+                numbers behind them — including the ones the catalogue types
+                as choices, a vocabulary-backed year — so a leaf whose schema
+                declares two can answer with four. `bag.reservedRangeAxes` is
+                what an earlier answer FOR THIS CATEGORY reported, remembered
+                in the state provider; when there is one it sizes the block,
+                because it is the count the swap will actually land on. */}
+            {props.categoryFeatures === undefined ? (
               <>
                 <Divider style={{ margin: 0 }} />
-                <Flex
-                  vertical
-                  gap={spacing[3]}
-                  data-testid="search-ranges-attributes"
-                >
-                  {attributeRanges.map((group) => (
-                    <RangeFilterRow
-                      key={group.slug}
-                      group={group}
-                      onApply={bag.setRange}
-                    />
-                  ))}
-                </Flex>
+                <div
+                  aria-hidden="true"
+                  data-testid="search-ranges-attributes-reserve"
+                  style={{ minBlockSize: RANGE_ROW_MIN_HEIGHT }}
+                />
               </>
+            ) : (
+              (attributeRanges.length > 0 || reservedAxes > 0) && (
+                <>
+                  <Divider style={{ margin: 0 }} />
+                  <Flex
+                    vertical
+                    gap={spacing[3]}
+                    data-testid="search-ranges-attributes"
+                  >
+                    {bag.state.status === "ready"
+                      ? attributeRanges.map((group) => (
+                          <RangeFilterRow
+                            key={group.slug}
+                            group={group}
+                            onApply={bag.setRange}
+                          />
+                        ))
+                      : Array.from({ length: reservedAxes }, (_, index) => (
+                          <RangeRowSkeleton key={index} />
+                        ))}
+                  </Flex>
+                </>
+              )
             )}
 
             {footerBar !== "none" && (

package/src/default/FilterChips.tsx

@@ -472,6 +472,7 @@ function OpenerChipRow(props: FilterChipsOpenerProps): ReactElement | null {
       ? { categoryFeatures: props.categoryFeatures }
       : {}),
     coreRanges: bag.coreRanges,
+    ...(bag.ranges !== undefined ? { ranges: bag.ranges } : {}),
     ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
     t,
   });
@@ -866,6 +867,7 @@ function AppliedChipRow(props: FilterChipsAppliedProps): ReactElement | null {
       ? { categoryFeatures: props.categoryFeatures }
       : {}),
     coreRanges: bag.coreRanges,
+    ...(bag.ranges !== undefined ? { ranges: bag.ranges } : {}),
     ...(bag.currency !== undefined ? { currency: bag.currency } : {}),
     t,
   });

package/src/default/RangeFilterRow.tsx

@@ -12,12 +12,16 @@
  * range is TWO fields, and committing each keystroke would run a search for
  * `1`, `10`, `100` on the way to `1000` — three wrong result pages, three
  * history entries' worth of churn, and a facet panel that reshuffles under the
- * hand still typing. So the row holds a draft and commits on Apply (or Enter),
- * which is also what makes "from > to" refusable instead of merely empty.
+ * hand still typing. So the row holds a draft and commits on Apply, Enter, or
+ * leaving the field (blur) — the picker bounds already committed on blur, and
+ * a typed bound doing nothing until a second, separate click is a surprise
+ * the picker never had — which is also what makes "from > to" refusable
+ * instead of merely empty. A blur that changed nothing sends nothing, and
+ * Enter followed by the blur it does not itself cause never double-commits.
  */
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
-import { Button, Flex, InputNumber, Select, Typography } from "antd";
+import { Button, Flex, InputNumber, Select, Skeleton, Typography } from "antd";
 import { actionAvailable, actionBlocked, useFormat, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
 import { GatedButton } from "@stapel/tokens-antd/skin";
@@ -30,6 +34,49 @@ import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 /** Floor width of one bound field, so two of them fit a 390px phone row. */
 export const RANGE_FIELD_MIN_WIDTH = 96;
 
+/**
+ * One row's reserved block-size — a label line plus one control row, the two
+ * lines every real row draws. Used both as the skeleton row's floor and as
+ * the whole reserve when the schema itself is not known yet (D361: a 53px
+ * jump inside the rail when the attribute-range block had no box to arrive
+ * into, because nothing reserved its height before the answer landed).
+ */
+export const RANGE_ROW_MIN_HEIGHT = 76;
+
+/** Floor width of the label placeholder in {@link RangeRowSkeleton} — a
+ * named one-off, not a spacing step: it bounds a text skeleton, not a gap. */
+const RANGE_SKELETON_LABEL_WIDTH = 160;
+
+/**
+ * The unrevealed shape of one range row — same two lines, same field widths,
+ * no numbers. Drawn for a slug the schema already names while the answer
+ * that would fill it (bounds, applied value, unit) has not landed yet, so
+ * the rail's box is the row's own final height from the first paint rather
+ * than growing into it once the real row replaces this one.
+ */
+export function RangeRowSkeleton(): ReactElement {
+  return (
+    <Flex
+      vertical
+      gap={spacing[1]}
+      aria-hidden="true"
+      data-testid="facet-range-skeleton"
+      style={{ minBlockSize: RANGE_ROW_MIN_HEIGHT }}
+    >
+      <Skeleton.Input
+        active
+        size="small"
+        style={{ maxWidth: RANGE_SKELETON_LABEL_WIDTH }}
+      />
+      <Flex gap={spacing[2]} align="center" wrap>
+        <Skeleton.Input active style={{ minWidth: RANGE_FIELD_MIN_WIDTH }} />
+        <Skeleton.Input active style={{ minWidth: RANGE_FIELD_MIN_WIDTH }} />
+        <Skeleton.Button active />
+      </Flex>
+    </Flex>
+  );
+}
+
 export interface RangeFilterRowProps {
   readonly group: RangeGroup;
   /** `null` clears the slug's range entirely. */
@@ -175,8 +222,14 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
   // results are no longer about.
   const applied = useRef<string>(`${toDraft(group.from)}..${toDraft(group.to)}`);
   const current = `${toDraft(group.from)}..${toDraft(group.to)}`;
+  // What the row last SENT — starts equal to the URL's own value, so a blur
+  // that never changed anything commits nothing. Enter and blur both go
+  // through {@link commit}, and both read this ref, so pressing Enter and
+  // then tabbing out of the same field fires the request once, not twice.
+  const lastSent = useRef<string>(current);
   if (applied.current !== current) {
     applied.current = current;
+    lastSent.current = current;
     if (from !== toDraft(group.from)) setFrom(toDraft(group.from));
     if (to !== toDraft(group.to)) setTo(toDraft(group.to));
   }
@@ -193,6 +246,9 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
 
   const commit = (): void => {
     if (!usable) return;
+    const draftKey = `${from}..${to}`;
+    if (draftKey === lastSent.current) return;
+    lastSent.current = draftKey;
     props.onApply(group.slug, empty ? null : draft);
   };
 
@@ -267,6 +323,7 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
             setFrom(value === null || value === undefined ? "" : String(value));
           }}
           onPressEnter={commit}
+          onBlur={commit}
         />
         <InputNumber
           value={to === "" ? null : Number(to)}
@@ -284,6 +341,7 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
             setTo(value === null || value === undefined ? "" : String(value));
           }}
           onPressEnter={commit}
+          onBlur={commit}
         />
         </>
         )}

package/src/default/SearchPage.tsx

@@ -552,6 +552,10 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const ranges = buildRangeGroups({
     state,
     ...(categoryFeatures !== undefined ? { categoryFeatures } : {}),
+    // The answer's measured axes count as rows here too: a leaf whose numeric
+    // axes are all vocabulary-backed has filters, and the schema alone would
+    // have called that column empty.
+    ...(facets.ranges !== undefined ? { ranges: facets.ranges } : {}),
   });
   const filtersEmpty =
     facets.state.status === "ready" &&

package/src/headless/FacetPanel.tsx

@@ -5,16 +5,21 @@ import type { FeatureDef } from "@stapel/attributes-react";
 import type {
   FacetCategoryCount,
   FacetMeta,
+  FacetRangesMap,
   FacetWithheldGroup,
   SearchRange,
 } from "../api/types.js";
 import { useSearchQuery } from "../model/queries.js";
 import { buildFacetGroups } from "../state/facets.js";
-import { FACET_PLAN_EVIDENCE } from "../state/degradations.js";
+import { FACET_PLAN_EVIDENCE, FACET_RANGES } from "../state/degradations.js";
 import type { FacetGroup } from "../state/facets.js";
 import { useHostFacetLabels } from "./useFacetLabels.js";
 import type { FacetLabelResolver } from "./useFacetLabels.js";
-import { useSearchState } from "./SearchStateProvider.js";
+import {
+  usePublishRangeAxes,
+  useRememberedRangeAxes,
+  useSearchState,
+} from "./SearchStateProvider.js";
 
 /** The bag `<FacetPanel>` hands its render prop. */
 export interface FacetPanelBag {
@@ -48,6 +53,29 @@ export interface FacetPanelBag {
    * filter the deployed server would answer zero for.
    */
   readonly coreRanges: readonly string[];
+  /**
+   * `facet_meta.ranges` — the ends this answer MEASURED per axis, core
+   * columns and attributes in one map (stapel-search 0.14.7+).
+   *
+   * `undefined` when the server said nothing: it predates the report, or its
+   * engine has no `ranges` verb and said so ({@link rangesDegraded}). A rail
+   * falls back to the schema's declared bounds then; it never reads the
+   * silence as "this category has no numbers".
+   */
+  readonly ranges: FacetRangesMap | undefined;
+  /** `true` when the engine listed `facet_ranges` in `degraded[]` — no axis
+   * was measured, and that is an engine fact, not a corpus fact. */
+  readonly rangesDegraded: boolean;
+  /**
+   * The attribute axes an answer has already reported FOR THIS CATEGORY,
+   * remembered in the state provider across answers — or `undefined` when
+   * none ever has.
+   *
+   * A skin sizes its reservation with it: the schema's numeric count is the
+   * first guess, and this is what the server turned out to measure, so the
+   * block does not jump the second time a person opens the same leaf.
+   */
+  readonly reservedRangeAxes: readonly string[] | undefined;
   /**
    * 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
@@ -208,12 +236,34 @@ export function useFacetPanel(props: {
   // then this. See `useFacetLabels.ts`.
   const labelled = useHostFacetLabels(groups, props.resolveFacetLabels, props.locale);
 
+  // An engine with no `ranges` verb reports it; its empty map is then an
+  // engine fact, and reading it as "no numeric axes here" is exactly the
+  // appear-then-vanish rail this release removes.
+  const rangesDegraded =
+    envelope.status === "ready" && envelope.data.degraded.includes(FACET_RANGES);
+  const coreRanges = meta.core_ranges ?? [];
+  const measured =
+    envelope.status === "ready" && !rangesDegraded ? meta.ranges : undefined;
+  // Remembered per category, and only the ATTRIBUTE half: the core axes are
+  // declared by the server for every document and never part of the
+  // schema-sized block a rail reserves.
+  usePublishRangeAxes(
+    searchState.category,
+    measured === undefined
+      ? undefined
+      : Object.keys(measured).filter((slug) => !coreRanges.includes(slug))
+  );
+  const reservedRangeAxes = useRememberedRangeAxes(searchState.category);
+
   return {
     state: labelled,
     approximate: meta.approximate,
     skipped: meta.skipped,
     counted: meta.counted,
-    coreRanges: meta.core_ranges ?? [],
+    coreRanges,
+    ranges: measured,
+    rangesDegraded,
+    reservedRangeAxes,
     currency:
       envelope.status === "ready"
         ? envelope.data.items.find((item) => typeof item.card?.["currency"] === "string")

package/src/headless/SearchStateProvider.tsx

@@ -256,6 +256,75 @@ export function useFacetKeys(): FacetKeyMap {
   return useContext(FacetKeysContext)?.keys ?? EMPTY_FACET_KEYS;
 }
 
+/**
+ * WHICH NUMERIC AXES A CATEGORY HAS — remembered across answers.
+ *
+ * The rail reserves a box per numeric axis before the answer lands (D361),
+ * and until 0.14.7 the only thing that could count them was the category
+ * SCHEMA. The answer now knows better: `facet_meta.ranges` measures the axes
+ * that have numbers behind them, including the vocabulary-backed ones the
+ * schema calls choices. A schema count of 2 followed by a measured count of 4
+ * is the SAME layout jump the reservation exists to stop, one answer later.
+ *
+ * So the count is remembered, keyed by the category it was measured in —
+ * different leaves have different axes, and remembering one number for all of
+ * them would reserve a car's rail on a phone leaf. Memory, not cache: it is
+ * only ever read to size a placeholder, never to draw a row, so a stale entry
+ * costs a few pixels and never a wrong control.
+ */
+export type RangeAxisMemory = Readonly<Record<string, readonly string[]>>;
+
+interface RangeAxisRegistry {
+  readonly axes: RangeAxisMemory;
+  publish(category: string, slugs: readonly string[]): void;
+}
+
+const RangeAxesContext = createContext<RangeAxisRegistry | null>(null);
+
+const EMPTY_RANGE_AXES: RangeAxisMemory = {};
+
+/** The memory key for a search: its category path, or `""` for none. */
+function axisKey(category: string | undefined): string {
+  return category ?? "";
+}
+
+function sameAxes(a: readonly string[] | undefined, b: readonly string[]): boolean {
+  return (
+    a !== undefined && a.length === b.length && a.every((slug, i) => slug === b[i])
+  );
+}
+
+/**
+ * Publish the axes an answer MEASURED for the category it answered about.
+ *
+ * `slugs` is `undefined` when the server said nothing — it predates 0.14.7,
+ * or its engine listed `facet_ranges` in `degraded[]`. Nothing is written
+ * then, and nothing is forgotten: an empty list from a degraded answer would
+ * teach the rail that this category has no numeric axes at all.
+ */
+export function usePublishRangeAxes(
+  category: string | undefined,
+  slugs: readonly string[] | undefined
+): void {
+  const registry = useContext(RangeAxesContext);
+  const key = axisKey(category);
+  const joined = slugs === undefined ? undefined : slugs.join("");
+  useEffect(() => {
+    if (registry === null || joined === undefined) return;
+    registry.publish(key, joined === "" ? [] : joined.split(""));
+  }, [registry, key, joined]);
+}
+
+/**
+ * The axes an answer has already reported for this category, or `undefined`
+ * when none ever has.
+ */
+export function useRememberedRangeAxes(
+  category: string | undefined
+): readonly string[] | undefined {
+  return useContext(RangeAxesContext)?.axes[axisKey(category)];
+}
+
 export interface SearchStateProviderProps extends ParseSearchStateOptions {
   readonly adapter: SearchParamsAdapter;
   /**
@@ -334,6 +403,20 @@ export function SearchStateProvider(
     [facetKeys]
   );
 
+  // The measured axis lists, per category — see `RangeAxesContext`.
+  const [rangeAxes, setRangeAxes] = useState<RangeAxisMemory>(EMPTY_RANGE_AXES);
+  const axisRegistry = useMemo<RangeAxisRegistry>(
+    () => ({
+      axes: rangeAxes,
+      publish: (category, slugs) => {
+        setRangeAxes((was) =>
+          sameAxes(was[category], slugs) ? was : { ...was, [category]: slugs }
+        );
+      },
+    }),
+    [rangeAxes]
+  );
+
   const parsed = useMemo(
     () =>
       parseSearchState(new URLSearchParams(search), {
@@ -447,7 +530,9 @@ export function SearchStateProvider(
 
   return (
     <FacetKeysContext.Provider value={registry}>
-      <StateContext.Provider value={bag}>{children}</StateContext.Provider>
+      <RangeAxesContext.Provider value={axisRegistry}>
+        <StateContext.Provider value={bag}>{children}</StateContext.Provider>
+      </RangeAxesContext.Provider>
     </FacetKeysContext.Provider>
   );
 }