@stapel/search-react 0.31.0 → 0.32.1

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/search-react 0.31.0
+# @stapel/search-react 0.32.1
 
-Headless React flow pair for stapel-search (contract >=0.15 <0.16) — business + state, zero visual opinion.
+Headless React flow pair for stapel-search (contract >=0.16 <0.17) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 
@@ -85,10 +85,10 @@ const { tracked } = useTracked();
 - search.language-select → <LanguageSelect> [offered|from-a-link]  demo/LanguageSelect.demo.tsx
 - search.location-summary → <LocationSummaryLine> [everywhere|placed|narrowed|long-place|wide]  demo/LocationSummaryLine.demo.tsx
 - search.other-categories-line → <OtherCategoriesLine> [line|narrow|empty]  demo/OtherCategoriesLine.demo.tsx
-- search.page → <SearchPage> [desktop|phone|unreadable-link]  demo/SearchPage.demo.tsx
+- search.page → <SearchPage> [desktop|phone|catalogue-leaf|unreadable-link]  demo/SearchPage.demo.tsx
 - search.page-size-select → <PageSizeSelect> [ladder|off-ladder]  demo/PageSizeSelect.demo.tsx
 - search.partition-chips → <PartitionChips> [parent|child]  demo/PartitionChips.demo.tsx
-- search.popular-values → <PopularValues> [desktop|narrow-column]  demo/PopularValues.demo.tsx
+- search.popular-values → <PopularValues> [desktop|responsive|narrow-column]  demo/PopularValues.demo.tsx
 - search.range-filter-row → <RangeFilterRow> [untouched|applied]  demo/RangeFilterRow.demo.tsx
 - search.ranking-pane → <RankingDisclosurePane> [desktop|phone]  demo/RankingDisclosurePane.demo.tsx
 - search.result-card → <SearchResultCard> [gallery|promoted|unresolved|plain]  demo/SearchResultCard.demo.tsx

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "backend": {
     "module": "stapel-search",
-    "contract": ">=0.15 <0.16"
+    "contract": ">=0.16 <0.17"
   },
   "layers": [
     "api",
@@ -580,6 +580,7 @@
       "variants": [
         "desktop",
         "phone",
+        "catalogue-leaf",
         "unreadable-link"
       ],
       "source": "demo/SearchPage.demo.tsx"
@@ -619,6 +620,7 @@
       ],
       "variants": [
         "desktop",
+        "responsive",
         "narrow-column"
       ],
       "source": "demo/PopularValues.demo.tsx"
@@ -1009,6 +1011,7 @@
       "navEntries",
       "offerableCategories",
       "orderFacetGroupsBySchema",
+      "orderPanelItems",
       "otherCategoryLeaf",
       "ownsParam",
       "parseDegradations",
@@ -1043,12 +1046,14 @@
       "useSearchRuntime",
       "useSearchState",
       "useSuggest",
+      "withheldSlugs",
       "writeSearchState"
     ],
     "types": [
       "BuildFacetGroupsInput",
       "BuildRangeGroupsInput",
       "CreateSearchRuntimeOptions",
+      "FacetAxisKind",
       "FacetCategoryCount",
       "FacetGroup",
       "FacetKeyMap",
@@ -1060,13 +1065,18 @@
       "FacetMeta",
       "FacetOption",
       "FacetPanelBag",
+      "FacetRangeAxis",
       "FacetRangeBounds",
       "FacetRangesMap",
       "FacetSelection",
+      "FacetWithheldAxis",
       "FacetWithheldGroup",
+      "FacetWithheldReason",
       "HistoryMode",
+      "OrderPanelItemsInput",
       "OtherCategoriesBag",
       "OtherCategoryRow",
+      "PanelItem",
       "ParseSearchStateOptions",
       "ParsedSearchState",
       "RangeAxisMemory",

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/search-react",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "entries": [
     {
       "id": "search.results",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -52,14 +52,14 @@
   ],
   "size-limit": [
     {
-      "name": "index — the headless pair (client + hooks + URL codec + facet model incl. the facetability rule, the label-source order, the across-alphabets prefix matcher, the SCHEMA-order comparator that puts a category's required axes first and the bounded-integer picker list): no antd, no react-router. Raised 12 → 12.5 KB for the rail-order comparator, the shared drawability predicate (one rule for the rail and the chip row) and the picker bounds. Raised 12.5 → 13 KB for `useOtherCategories`, which reads the sections an answer is made of out of `facet_meta.categories` — the read that replaced a storefront's second request, then 13 → 13.5 KB for the SHORT FEATURE KEYS: the two-direction `url_key` map (built with the server's own collision rules, so an ambiguous short form keeps the slug on both sides), its publication seam from the answer up to the state provider, and the vocabulary-backed predicate the drawability rule and the dictionary shape now share, then 13.5 → 13.75 KB for the documented history policy (`DEFAULT_HISTORY_MODE`, one push/replace table every mutator follows instead of an ad hoc boolean per call) and the codec omitting `type`/`sort`/`limit` from the address when they equal the default a host declared, then 13.75 → 14 KB for the MEASURED range axes: `facet_meta.ranges` on the envelope, the bounds/picker rule that prefers what an answer measured over what a catalogue declares (and draws a row for a vocabulary-backed numeric axis the schema types as a choice), and the per-category axis memory the rail reserves its box from",
+      "name": "index — the headless pair (client + hooks + URL codec + facet model incl. the facetability rule, the label-source order, the across-alphabets prefix matcher, the SCHEMA-order comparator that puts a category's required axes first and the bounded-integer picker list): no antd, no react-router. Raised 12 → 12.5 KB for the rail-order comparator, the shared drawability predicate (one rule for the rail and the chip row) and the picker bounds. Raised 12.5 → 13 KB for `useOtherCategories`, which reads the sections an answer is made of out of `facet_meta.categories` — the read that replaced a storefront's second request, then 13 → 13.5 KB for the SHORT FEATURE KEYS: the two-direction `url_key` map (built with the server's own collision rules, so an ambiguous short form keeps the slug on both sides), its publication seam from the answer up to the state provider, and the vocabulary-backed predicate the drawability rule and the dictionary shape now share, then 13.5 → 13.75 KB for the documented history policy (`DEFAULT_HISTORY_MODE`, one push/replace table every mutator follows instead of an ad hoc boolean per call) and the codec omitting `type`/`sort`/`limit` from the address when they equal the default a host declared, then 13.75 → 14 KB for the MEASURED range axes: `facet_meta.ranges` on the envelope, the bounds/picker rule that prefers what an answer measured over what a catalogue declares (and draws a row for a vocabulary-backed numeric axis the schema types as a choice), and the per-category axis memory the rail reserves its box from, then 14 → 14.5 KB for ONE PANEL and the named axis: a RangeAxis carrying its own label/unit/order instead of two bare numbers, the withheld rows that say which axis was dropped and why, `orderPanelItems` merging groups and ranges into a single sequence, and `setRanges` committing a whole panel in one state change. Measured with dependencies held constant, this package's src at the commit before that work and then at it: 13.95 -> 14.28 KB. 330 B is what it costs to stop drawing `kilometrage` as a heading over a picker — an axis nobody named is now dropped rather than captioned from its slug, and the model has to carry the name to know that",
       "path": "dist/index.js",
-      "limit": "14 KB"
+      "limit": "14.5 KB"
     },
     {
-      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes, then 29.25 → 30.5 KB for the panel that draws all of it: groups and ranges as one ordered sequence with one «Apply» for the panel rather than one per row, the empty-group heading rule, `categoryFilter={false}` and the `resultsLead` slot for a page reached by walking the catalogue, `PopularValues columns=\\\"responsive\\\"` on a container query, `SortSelect` annotating a blocked option at every width, a loading arm that covers the whole pane (0.34 CLS on a live host), and the chip row reserving its own box (a further 0.045). Measured with dependencies held constant, this package's src at the commit before that work and then at it: 29.05 -> 30.16 KB — 1.11 KB, and every part of it is a shift or a mislabelled control a host was living with",
       "path": "dist/default/index.js",
-      "limit": "29.25 KB"
+      "limit": "30.5 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -115,12 +115,12 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/core": "^0.25.1",
+    "@stapel/attributes-react": "^0.16.1",
+    "@stapel/core": "^0.25.4",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
-    "@stapel/tokens": "^0.7.0",
-    "@stapel/tokens-antd": "^0.17.0",
-    "@stapel/attributes-react": "^0.16.0"
+    "@stapel/tokens": "^0.8.0",
+    "@stapel/tokens-antd": "^0.17.2"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -135,6 +135,12 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /**
+         * @description * `group` - group
+         *     * `range` - range
+         * @enum {string}
+         */
+        AxisEnum: "group" | "range";
         /** @description One partition of the answer — a heading, never a filter over it. */
         BandSummary: {
             id: components["schemas"]["IdEnum"];
@@ -233,6 +239,8 @@ export interface components {
             vocabulary: string | null;
             /** @description The vocabulary level `vocabulary` resolves against. Present only alongside a non-null `vocabulary`. */
             level?: string;
+            /** @description Where this group sits in ONE panel, numbered together with the numeric axes in `facet_meta.ranges` — draw both halves sorted by it and price and year land where the category's schema puts them, among the makes and models rather than below all of them. Core ranges take the first positions (they exist for every document in every category); the rest follow the plan's own order, which for a category's own schema is mandatory first and then as authored. `null` when the plan has no position for the group, which a client sorts last. */
+            order: number | null;
         };
         FacetMeta: {
             /** @description True when counts came from a sample because the candidate set exceeded FACET_CANDIDATE_CAP. */
@@ -246,16 +254,22 @@ 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. */
+            /** @description `{slug: {min, max, label, label_translatable, unit?, order}}` — every numeric axis that HAS a number on this page, core columns (`price`) and attributes (`year`, `mileage`, `engine_volume`) alike, with everything needed to DRAW it. What a from/to picker is made of: 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 either has no numbers behind it in this candidate set — a different fact from a bound of zero — or was WITHHELD, and then it is named in `withheld` with the reason. Capped by MAX_FACET_FIELDS since 0.16.0: the budget is how wide a panel may be, and a from/to picker is as wide as a bucket list. Empty, with `facet_ranges` in `degraded[]`, on an engine that does not implement the optional `ranges` verb. */
             ranges: {
-                [key: string]: unknown;
+                [key: string]: components["schemas"]["RangeAxis"];
             };
             /** @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. */
-            withheld: {
-                [key: string]: unknown;
-            }[];
+            /**
+             * @description Axes this answer planned and then did not offer, each naming which half of the panel it is about (`axis`) and why (`reason`). 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.
+             *
+             *     `coverage` — counted, then withheld for describing too little of the result set (FACET_MIN_COVERAGE), with the two numbers. For a GROUP only slugs the evidence plan borrowed from another category are ever measured, because a group the queried category authored answers with its zeros on purpose; for a RANGE every non-core axis is, because a range has no zeros to answer with and a slider over three of fifty-two documents narrows nothing whoever authored it.
+             *
+             *     `unlabelled` (0.16.0, ranges) — no caption could be resolved from any source, so a client could only print the storage slug above the picker. `doors` and `kilometrage` in a chip row is an axis that was there and unreadable.
+             *
+             *     An axis the reader has already filtered on is never withheld for any reason: that would leave the filter applied with no control to undo it.
+             */
+            withheld: components["schemas"]["WithheldAxis"][];
             /** @description `{category, count}` — the categories this answer's candidate set is made of, busiest first, `category` being the same slash-joined id path the `category` filter takes. The evidence the plan was drawn from, and what a panel needs to offer the CATEGORY itself as the first filter on a text search. Empty when the plan is the queried category's own. */
             categories: {
                 [key: string]: unknown;
@@ -307,6 +321,27 @@ export interface components {
             residual: string;
             degraded: string[];
         };
+        /** @description One numeric axis a from/to picker is drawn from, with its caption. */
+        RangeAxis: {
+            /**
+             * Format: double
+             * @description The low end of the axis over this candidate set, measured with the range filters removed. A number, not a string: a slider end is arithmetic the client does immediately. Integral values render integral, so a year is `2015` and an engine volume is `1.4`.
+             */
+            min: number;
+            /**
+             * Format: double
+             * @description The high end, same rule as `min`.
+             */
+            max: number;
+            /** @description What to write above the picker. Resolved from the SAME source a facet group's heading comes from — the category's own feature definition — because a group and a range are two ways of narrowing one authored feature. A core range (`price`) has no definition to read and takes this library's own key. Never null: an axis with no resolvable caption is withheld instead (`withheld`, reason `unlabelled`), because a chip row printing `doors` and `kilometrage` at a reader is an axis that was there and unreadable. */
+            label: string;
+            /** @description True when `label` is a translation KEY, false when it is literal text the catalogue wrote. The reader cannot tell by looking. */
+            label_translatable: boolean;
+            /** @description What the numbers are measured in — `postfix` off the feature definition, or the family's BASE unit for a `convertible_unit` (the stored value is in the base unit, so naming the input unit would label metres as kilometres). A translation key or literal text, exactly as the catalogue wrote it; this module never translates. ABSENT, not empty, for an axis whose definition names no unit — `price` among them, because a price's unit is the corpus's base currency and a property of each document rather than of the axis. */
+            unit?: string;
+            /** @description Where this axis sits in ONE panel, numbered together with the groups in `facet_labels`. Same field, same sequence: draw both halves sorted by it and the picker lands where the schema put it. */
+            order: number | null;
+        };
         /** @description The P2B Art. 5 disclosure, generated from the scorer registry. */
         RankingResponse: {
             doc_type: string;
@@ -314,6 +349,12 @@ export interface components {
             scorers: components["schemas"]["Scorer"][];
             notes: string[];
         };
+        /**
+         * @description * `coverage` - coverage
+         *     * `unlabelled` - unlabelled
+         * @enum {string}
+         */
+        ReasonEnum: "coverage" | "unlabelled";
         ReindexRequest: {
             doc_type: string;
             /** @description Re-pull exactly these keys; omit to rebuild the whole type. */
@@ -418,6 +459,28 @@ export interface components {
             degraded: string[];
             backend: string;
         };
+        /** @description One axis that was planned and then not offered, and why. */
+        WithheldAxis: {
+            slug: string;
+            /**
+             * @description Which half of the panel this row is about — the bucket list or the from/to picker. One slug can be both (an imported `year` is a choice AND a measurement) and the two are decided by different quantities over the same page, so a withheld `group` row does not mean the slider is gone, or the other way round.
+             *
+             *     * `group` - group
+             *     * `range` - range
+             */
+            axis: components["schemas"]["AxisEnum"];
+            /**
+             * @description `coverage` — it describes too little of this result set (FACET_MIN_COVERAGE). `unlabelled` — no caption could be resolved, so a client could only print the storage slug at a reader. A closed set: an unknown value means the client is older than the server.
+             *
+             *     * `coverage` - coverage
+             *     * `unlabelled` - unlabelled
+             */
+            reason: components["schemas"]["ReasonEnum"];
+            /** @description How many documents the axis describes. Present on `coverage` only — it is the measurement that decided. */
+            coverage?: number;
+            /** @description What it was a share OF. Present on `coverage` only. */
+            candidates?: number;
+        };
     };
     responses: never;
     parameters: never;

package/src/api/types.ts

@@ -33,8 +33,25 @@ export type Schemas = components["schemas"];
  */
 export type FacetLabels = Omit<
   Schemas["FacetLabels"],
-  "label" | "label_translatable" | "url_key" | "vocabulary"
+  "label" | "label_translatable" | "url_key" | "vocabulary" | "order"
 > & {
+  /**
+   * Where this group sits in ONE panel, numbered together with the numeric
+   * axes of `facet_meta.ranges` (stapel-search 0.16.0+).
+   *
+   * The whole point of the field is that it is the SAME sequence: a group and
+   * a range are two ways of narrowing one authored feature, and sorting both
+   * halves by this key puts "Price" and "Year" where the category's schema put
+   * them instead of stacking every choice above every measurement. `null` is
+   * the server saying the plan has no position for this group, which sorts
+   * last.
+   *
+   * WHY IT IS NOT THE GENERATED SHAPE: 0.16.0 declares it REQUIRED, and a
+   * fixture captured from a 0.15 answer — or a group a host builds by hand —
+   * carries no `order` at all. Optional here, and the panel reads absence and
+   * `null` the same way: no position, sort last.
+   */
+  readonly order?: number | null;
   readonly label?: string | null;
   /**
    * Whether {@link label} is a translation KEY rather than a caption, the way
@@ -110,18 +127,61 @@ export type SearchResponse = Omit<
 export type SearchItem = Schemas["SearchItem"];
 
 /**
- * One group the counter COUNTED and then held back, because its buckets
- * describe too little of the result set (`FACET_MIN_COVERAGE`).
+ * One axis the server PLANNED and then did not offer, and why
+ * (stapel-search 0.16.0's `WithheldAxis`).
  *
  * The existence of this list is what makes "this search offers no filters"
- * a false sentence whenever it is not empty (D175).
+ * a false sentence whenever it is not empty (D175). Two things 0.16.0 added,
+ * and both matter to a panel:
+ *
+ *  - `axis` says WHICH HALF the row is about. One slug can be a choice and a
+ *    measurement at once — an imported `year` is both — and the two are
+ *    decided by different quantities over the same page, so a withheld
+ *    `group` row does not mean the slider is gone. A surface that counts the
+ *    list filters by `axis`; a surface that hides an axis reads only the rows
+ *    for its own half.
+ *  - `reason` is a CLOSED set. `coverage` is the old case (it describes too
+ *    little of the result set, and then the two numbers are present).
+ *    `unlabelled` is the new one: no caption could be resolved anywhere, so
+ *    the only thing a client could draw above the picker is the storage slug
+ *    — `doors`, `kilometrage`, printed at a buyer. That axis is withheld
+ *    rather than shipped bare, and this row is how the panel knows it existed.
+ *
+ * `coverage` and `candidates` are therefore OPTIONAL: they are the
+ * measurement that decided a `coverage` row and mean nothing on an
+ * `unlabelled` one.
  */
-export interface FacetWithheldGroup {
-  readonly slug: string;
-  /** Sum of that group's bucket counts — how much of the set it describes. */
-  readonly coverage: number;
-  /** Size of the candidate set `coverage` is a fraction of. */
-  readonly candidates: number;
+export type FacetWithheldAxis = Schemas["WithheldAxis"];
+
+/**
+ * @deprecated The 0.15-era name, kept for one minor so a host that imported
+ * it still compiles. It now denotes {@link FacetWithheldAxis}, which is the
+ * same row plus `axis` and `reason`.
+ */
+export type FacetWithheldGroup = FacetWithheldAxis;
+
+/** Which half of the panel a {@link FacetWithheldAxis} row is about. */
+export type FacetAxisKind = Schemas["AxisEnum"];
+
+/** Why an axis was withheld — a closed set; an unknown value means the client
+ * is older than the server. */
+export type FacetWithheldReason = Schemas["ReasonEnum"];
+
+/**
+ * The slugs one half of the panel must NOT draw, out of the answer's
+ * `withheld` list.
+ *
+ * Filtering by `axis` is the whole reason the field exists: a `year` withheld
+ * as a GROUP is still a slider, and a `year` withheld as a RANGE is still a
+ * bucket list. Reading the list without the discriminator hides both.
+ */
+export function withheldSlugs(
+  withheld: readonly FacetWithheldAxis[] | undefined,
+  axis: FacetAxisKind
+): readonly string[] {
+  return (withheld ?? [])
+    .filter((row) => row.axis === axis)
+    .map((row) => row.slug);
 }
 
 /** One category the candidate set is made of. */
@@ -134,41 +194,81 @@ export interface FacetCategoryCount {
 }
 
 /**
- * The two ENDS of one numeric axis, measured over this answer's candidate set
- * with the range filters removed (stapel-search 0.14.7+).
+ * One numeric axis a from/to picker is drawn from — its two ENDS, measured
+ * over this answer's candidate set with the range filters removed, AND its
+ * caption (stapel-search 0.16.0's `RangeAxis`).
+ *
+ * `min`/`max` are 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.
  *
- * 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.
+ * The other three are 0.16.0's, and they are why a client stopped needing the
+ * category schema to write a heading:
+ *
+ *  - `label` comes from the same source a facet group's heading does — the
+ *    category's own `FeatureDef.name`, or this library's own key for a core
+ *    axis — and is never null, because an axis nobody could name is WITHHELD
+ *    (`facet_meta.withheld`, reason `unlabelled`) rather than shipped as a
+ *    bare `doors`. `label_translatable` says whether it is a key or literal
+ *    text the catalogue wrote, exactly as it does for a group.
+ *  - `unit` is the definition's `postfix`, or the family's BASE unit for a
+ *    `convertible_unit` — the stored value is in the base unit, so naming the
+ *    input unit would label metres as kilometres. ABSENT, never `""`, for an
+ *    axis whose definition names none (`price` among them: a price's unit is
+ *    the corpus's currency, a property of each document rather than of the
+ *    axis).
+ *  - `order` numbers this axis in the SAME sequence as `facet_labels`, so a
+ *    panel that sorts both halves by it lands the picker where the category
+ *    authored it.
+ *
+ * `label`, `label_translatable` and `order` are OPTIONAL here while the
+ * generated shape declares them required: a fixture captured off a 0.15
+ * server, and a map a host or a demo builds by hand, carry two numbers and
+ * nothing else. A type that promised the caption would compile while reading
+ * `undefined` from a field the compiler swore was there — and the label is
+ * exactly the field a panel must not guess at.
  */
-export interface FacetRangeBounds {
-  readonly min: number;
-  readonly max: number;
-}
+export type FacetRangeAxis = Omit<
+  Schemas["RangeAxis"],
+  "label" | "label_translatable" | "order"
+> & {
+  readonly label?: string;
+  readonly label_translatable?: boolean;
+  readonly order?: number | null;
+};
+
+/**
+ * @deprecated The 0.14-era name for the two bounds alone. It now denotes
+ * {@link FacetRangeAxis}, which is the same two numbers plus the caption.
+ */
+export type FacetRangeBounds = FacetRangeAxis;
 
 /**
- * `facet_meta.ranges` — `{slug: {min, max}}` for every axis this answer has
+ * `facet_meta.ranges` — `{slug: RangeAxis}` 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`.
+ * An axis ABSENT from the map either has no numbers behind it on this page —
+ * a different fact from a bound of zero — or was WITHHELD, and then it is
+ * named in `facet_meta.withheld` with the reason. 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
+ * them apart — see `state/ranges.ts`.
  */
-export type FacetRangesMap = Readonly<Record<string, FacetRangeBounds>>;
+export type FacetRangesMap = Readonly<Record<string, FacetRangeAxis>>;
 
 /**
  * The honesty block beside the counts: `approximate`, `candidates`,
  * `counted`, `skipped`, and (stapel-search 0.12.0+) where the facet plan came
  * from. Rendered, never swallowed (spec §4.2).
  *
- * WHAT THE GENERATOR LOST: drf-spectacular describes `withheld` and
- * `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.
+ * WHAT THE GENERATOR LOST: drf-spectacular describes `categories` as a bare
+ * `object` array, so the generated member is `{[key: string]: unknown}[]` — a
+ * field a panel has to read row by row arrives with no rows in the type. It is
+ * corrected here to the documented row shape. `withheld` was in the same state
+ * until stapel-search 0.16.0 gave it a named `WithheldAxis`; it is now
+ * generated, and is re-declared only to keep the `readonly` array this pair
+ * hands around.
  *
  * `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
@@ -184,7 +284,7 @@ export type FacetMeta = Omit<
   Schemas["FacetMeta"],
   "withheld" | "categories" | "ranges"
 > & {
-  readonly withheld: readonly FacetWithheldGroup[];
+  readonly withheld: readonly FacetWithheldAxis[];
   readonly categories: readonly FacetCategoryCount[];
   readonly ranges?: FacetRangesMap;
 };

package/src/default/FacetGroupControl.tsx

@@ -984,7 +984,29 @@ export interface FacetGroupControlProps {
   readonly onSetValues?: (slug: string, values: readonly string[]) => void;
 }
 
-export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
+/**
+ * Is this group a HEADING WITH NOTHING UNDER IT?
+ *
+ * A bucket list with no buckets draws a caption, a chevron, and an empty box
+ * — a control that cannot narrow anything, taking a row of a 280px rail and a
+ * stop in a screen reader's tour to say so. On a live laptops leaf that was
+ * six of six groups (D249), and `facetGroupIsDrawable` now keeps most of them
+ * off the rail; this is the last mile, for the group that reaches a surface
+ * anyway — a host's own list, a fixture, a slug the URL constrains whose
+ * options the answer never enumerated.
+ *
+ * A DICTIONARY group is the exemption and the only one. Its control is a
+ * FIELD over a vocabulary the answer never enumerated, so it works with no
+ * buckets at all — that is the whole reason the shape exists, and a make
+ * picker on a leaf holding three cars must not vanish for having three.
+ */
+export function facetGroupIsEmptyHeading(group: FacetGroup): boolean {
+  return group.options.length === 0 && facetGroupShape(group) !== "dictionary";
+}
+
+export function FacetGroupControl(
+  props: FacetGroupControlProps
+): ReactElement | null {
   const t = useT();
   const { group } = props;
   const [expanded, setExpanded] = useState(false);
@@ -995,6 +1017,12 @@ export function FacetGroupControl(props: FacetGroupControlProps): ReactElement {
   const disclosure = props.collapsible === true && props.heading !== false;
   const open = !disclosure || openState;
 
+  // Nothing to narrow by: no heading either. See `facetGroupIsEmptyHeading`.
+  // AFTER the hooks, never before one — the group can gain buckets on the next
+  // answer, and a component that stopped calling `useState` on the way there
+  // would be a different component to React.
+  if (facetGroupIsEmptyHeading(group)) return null;
+
   const limit =
     props.visibleOptions === null
       ? null