@stapel/search-react 0.29.1 → 0.30.1

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

@@ -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
@@ -894,7 +903,16 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                    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. */}
+                   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 }} />
@@ -905,7 +923,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 />
               </>
             ) : (
-              attributeRanges.length > 0 && (
+              (attributeRanges.length > 0 || reservedAxes > 0) && (
                 <>
                   <Divider style={{ margin: 0 }} />
                   <Flex
@@ -921,8 +939,8 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                             onApply={bag.setRange}
                           />
                         ))
-                      : attributeRanges.map((group) => (
-                          <RangeRowSkeleton key={group.slug} />
+                      : Array.from({ length: reservedAxes }, (_, index) => (
+                          <RangeRowSkeleton key={index} />
                         ))}
                   </Flex>
                 </>

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,8 +12,12 @@
  * 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";
@@ -218,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));
   }
@@ -236,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);
   };
 
@@ -310,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)}
@@ -327,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>
   );
 }

package/src/index.ts

@@ -55,6 +55,8 @@ export type {
   FacetLabels,
   FacetLabelsMap,
   FacetMeta,
+  FacetRangeBounds,
+  FacetRangesMap,
   FacetSelection,
   FacetWithheldGroup,
   RankingResponse,
@@ -107,6 +109,7 @@ export type {
 
 export {
   FACET_PLAN_EVIDENCE,
+  FACET_RANGES,
   countIsEstimate,
   countKind,
   degradationAudience,
@@ -190,10 +193,13 @@ export {
   SearchStateProvider,
   useFacetKeys,
   usePublishFacetKeys,
+  usePublishRangeAxes,
+  useRememberedRangeAxes,
   useSearchState,
 } from "./headless/SearchStateProvider.js";
 export type {
   HistoryMode,
+  RangeAxisMemory,
   SearchHistoryKind,
   SearchParamsAdapter,
   SearchStateBag,

package/src/state/degradations.ts

@@ -27,6 +27,19 @@ const SCORER_PREFIX = "scorer:";
  */
 export const FACET_PLAN_EVIDENCE = "facet_plan_evidence";
 
+/**
+ * "This engine has no `ranges` verb, so no axis was measured."
+ *
+ * Read raw for the same reason as {@link FACET_PLAN_EVIDENCE}: an empty
+ * `facet_meta.ranges` from a degraded answer is not "this category has no
+ * numbers", so the rail falls back to the SCHEMA's bounds instead of drawing
+ * a control with no ends — and, crucially, does not REMEMBER the empty list
+ * as the category's axis count. Kept out of the `KNOWN` table deliberately: it is
+ * an operator's engine choice, and the generic literal-beside-the-sentence
+ * fallback is the honest way to show one this build has no wording for.
+ */
+export const FACET_RANGES = "facet_ranges";
+
 const KNOWN: Readonly<Record<string, SearchDegradationKind>> = {
   typo_tolerance: "typo_tolerance",
   phrase_synonyms: "phrase_synonyms",