@stapel/search-react 0.31.0 → 0.32.0

package/src/default/RangeFilterRow.tsx

@@ -18,6 +18,24 @@
  * 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.
+ *
+ * ── One Apply for the panel, not one per row ──────────────────────────────
+ *
+ * That is the row STANDING ALONE. Inside a filter panel it is one of several,
+ * and a rail with a price, a year and a mileage drew three identical
+ * "Apply" buttons stacked down a 280px column — one per row, each
+ * committing its own two fields, so narrowing by two axes was two searches and
+ * two history entries, and the button beside the row a person had just typed
+ * into looked like the one that would apply everything.
+ *
+ * So a panel passes {@link RangeFilterRowProps.onDraft} and owns the button:
+ * the row then REPORTS its draft on every change and commits nothing by
+ * itself. Blur stops committing (there is a button now, and blurring one field
+ * to reach the next is not a decision), Enter reaches the panel's own commit
+ * through {@link RangeFilterRowProps.onCommit}, and "Clear" stays on the
+ * row because removing one applied constraint is not the same act as applying
+ * a draft. The standalone shape is unchanged, and is still what a host mounting
+ * one row gets.
  */
 import { useRef, useState } from "react";
 import type { ReactElement } from "react";
@@ -77,10 +95,36 @@ export function RangeRowSkeleton(): ReactElement {
   );
 }
 
+/** What one row reports to a panel that owns the Apply button. */
+export interface RangeDraft {
+  /** The two ends as typed, or `null` for "clear this slug". */
+  readonly range: SearchRange | null;
+  /** `false` for `100..50` — a pair the server would answer zero for, which
+   * reads as "there is nothing like this" instead of "you typed it
+   * backwards". A panel refuses to apply while any draft is unusable. */
+  readonly usable: boolean;
+  /** `true` when the draft differs from what the URL already carries — what
+   * makes the panel's button primary, and what stops an Apply over untouched
+   * rows sending anything. */
+  readonly dirty: boolean;
+}
+
 export interface RangeFilterRowProps {
   readonly group: RangeGroup;
   /** `null` clears the slug's range entirely. */
   readonly onApply: (slug: string, range: SearchRange | null) => void;
+  /**
+   * Report this row's draft instead of owning an Apply button — see the
+   * module note. Called on every change, and once on mount is NOT promised: a
+   * panel starts from "nothing pending", which is what an untouched row means.
+   */
+  readonly onDraft?: (slug: string, draft: RangeDraft) => void;
+  /**
+   * Commit everything the panel has collected. Only reachable in the collected
+   * shape, and only from Enter — the gesture that has always meant "I have
+   * finished typing this".
+   */
+  readonly onCommit?: () => void;
 }
 
 function toDraft(value: string | undefined): string {
@@ -243,6 +287,10 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
   const apply: ActionAvailability = usable
     ? actionAvailable()
     : actionBlocked(SEARCH_I18N_KEYS.facetsRangeInvalid);
+  // Who owns the Apply button — see the module note. `onDraft` is the panel
+  // saying "I have one for all of us".
+  const onDraft = props.onDraft;
+  const collected = onDraft !== undefined;
 
   const commit = (): void => {
     if (!usable) return;
@@ -252,6 +300,45 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
     props.onApply(group.slug, empty ? null : draft);
   };
 
+  /**
+   * Both halves of a change, in the shape the row is in.
+   *
+   * Standalone, a bound moves the local draft and nothing else until Apply,
+   * Enter or blur. Collected, the same move is also REPORTED — synchronously,
+   * from the event, with the values the change produces rather than the ones
+   * state still holds, because `setFrom` has not landed yet and a panel told
+   * the previous value would apply the number before last.
+   */
+  const change = (bound: "from" | "to", value: string): void => {
+    if (bound === "from") setFrom(value);
+    else setTo(value);
+    if (onDraft === undefined) return;
+    const nextFrom = bound === "from" ? value : from;
+    const nextTo = bound === "to" ? value : to;
+    const next: SearchRange = {
+      ...(nextFrom !== "" ? { from: nextFrom } : {}),
+      ...(nextTo !== "" ? { to: nextTo } : {}),
+    };
+    const blank = nextFrom === "" && nextTo === "";
+    onDraft(group.slug, {
+      range: blank ? null : next,
+      usable: isRangeUsable(next),
+      dirty: `${nextFrom}..${nextTo}` !== current,
+    });
+  };
+
+  /** Enter. The panel's commit when there is one, this row's otherwise. */
+  const enter = (): void => {
+    if (collected) props.onCommit?.();
+    else commit();
+  };
+
+  /** Blur. Nothing at all once a button owns the decision — leaving a field to
+   * reach the next one is not "apply this". */
+  const blur = (): void => {
+    if (!collected) commit();
+  };
+
   const suffix = boundSuffix(format, group);
   const unit = suffix === undefined ? "" : ` ${suffix}`;
   // Thousands grouping inside the field, because a price is read in
@@ -294,15 +381,19 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
               group={group}
               bound="from"
               value={from}
-              onChange={setFrom}
-              onCommit={commit}
+              onChange={(value) => {
+                change("from", value);
+              }}
+              onCommit={blur}
             />
             <BoundPicker
               group={group}
               bound="to"
               value={to}
-              onChange={setTo}
-              onCommit={commit}
+              onChange={(value) => {
+                change("to", value);
+              }}
+              onCommit={blur}
             />
           </>
         ) : (
@@ -320,10 +411,10 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           {...(group.max !== undefined ? { max: group.max } : {})}
           {...(group.step !== undefined ? { step: group.step } : {})}
           onChange={(value) => {
-            setFrom(value === null || value === undefined ? "" : String(value));
+            change("from", value === null || value === undefined ? "" : String(value));
           }}
-          onPressEnter={commit}
-          onBlur={commit}
+          onPressEnter={enter}
+          onBlur={blur}
         />
         <InputNumber
           value={to === "" ? null : Number(to)}
@@ -338,10 +429,10 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
           {...(group.max !== undefined ? { max: group.max } : {})}
           {...(group.step !== undefined ? { step: group.step } : {})}
           onChange={(value) => {
-            setTo(value === null || value === undefined ? "" : String(value));
+            change("to", value === null || value === undefined ? "" : String(value));
           }}
-          onPressEnter={commit}
-          onBlur={commit}
+          onPressEnter={enter}
+          onBlur={blur}
         />
         </>
         )}
@@ -351,22 +442,28 @@ export function RangeFilterRow(props: RangeFilterRowProps): ReactElement {
             button exists to submit (class C-NOPRIMARY). And no `size="small"`:
             a filter row that a phone cannot hit is not a filter row, and the
             shared `SkinTheme` only raises the DEFAULT control height to 44. */}
-        <GatedButton
-          gate={apply}
-          type={usable && !empty ? "primary" : "default"}
-          testId={`facet-range-${group.slug}-apply`}
-          data-analytics="none"
-          data-analytics-reason="a filter is a read, not a flow step"
-          onClick={commit}
-        >
-          {t(SEARCH_I18N_KEYS.facetsRangeApply)}
-        </GatedButton>
+        {!collected && (
+          <GatedButton
+            gate={apply}
+            type={usable && !empty ? "primary" : "default"}
+            testId={`facet-range-${group.slug}-apply`}
+            data-analytics="none"
+            data-analytics-reason="a filter is a read, not a flow step"
+            onClick={commit}
+          >
+            {t(SEARCH_I18N_KEYS.facetsRangeApply)}
+          </GatedButton>
+        )}
         {group.active && (
           <Button
             data-testid={`facet-range-${group.slug}-clear`}
             data-analytics="none"
             data-analytics-reason="a filter is a read, not a flow step"
             onClick={() => {
+              // The row's own draft goes with the constraint: leaving a
+              // pending `2015..` behind would let the panel's Apply put back
+              // exactly what this button just removed.
+              onDraft?.(group.slug, { range: null, usable: true, dirty: false });
               props.onApply(group.slug, null);
             }}
           >

package/src/default/SearchPage.tsx

@@ -240,6 +240,16 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * characteristic, and on a result list that is what a chip is.
    */
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  /**
+   * Draw the "Category" pane in the filter panel at all. Default `true`.
+   *
+   * `false` removes it entirely — see
+   * {@link FacetPanelPaneProps.categoryFilter}. The page passes it on and
+   * stops counting the category as a reason to keep the filter column open,
+   * so a leaf whose only other filter is a price does not get a column
+   * containing one pane the surface asked not to draw.
+   */
+  readonly categoryFilter?: boolean;
   /**
    * What the current category is CALLED — the chip's own text. The pair holds
    * a path of slugs and no way to turn one into a catalogue name; absent, the
@@ -270,7 +280,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    *
    * Defaulted PER LAYOUT rather than left to the panel's own default, because
    * the two frames want opposite shapes and only this component knows which
-   * one it is drawing: the desktop rail gets `"field"` (a select-style «Any»
+   * one it is drawing: the desktop rail gets `"field"` (a select-style "Any"
    * that opens the searchable list — a 418-value vocabulary held open in a
    * 280px column is the whole column), the phone sheet gets `"sheet"` — the
    * same trigger row, opening a nested picker with a search box, a
@@ -340,6 +350,23 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * describes the whole page, not the results column of it.
    */
   readonly resultsHeader?: ReactNode;
+  /**
+   * The top of the RESULTS COLUMN, above the toolbar and the heading row.
+   *
+   * The fifth slot, and the four before it were each checked first:
+   * `resultsHeader` spans the whole page (both columns on a desktop), which is
+   * right for a location row and wrong for anything that belongs over the list
+   * — a category's own description, a promoted band, a "12 new since
+   * yesterday" line all describe the RESULTS and would otherwise sit over the
+   * filter rail as well; `breadcrumb` is a walk up the category tree and
+   * renders above the heading; `resultsHeading` is the caption itself; the
+   * pane's `toolbar` is the row of controls this slot sits above.
+   *
+   * Rendered inside the column in BOTH layouts, so on a phone it is above the
+   * sort row and on a desktop it is above the sort row of the results column
+   * only.
+   */
+  readonly resultsLead?: ReactNode;
   /**
    * Draw the APPLIED filter row in the results header — one chip per applied
    * value and per applied range, each of which removes it
@@ -459,6 +486,8 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
+  readonly categoryFilter?: boolean;
+  readonly resultsLead?: ReactNode;
   readonly dictionaryMode?: "field" | "inline" | "sheet";
   readonly visibleGroups?: number | null;
   readonly categoryFeatures?: readonly FeatureDef[];
@@ -568,9 +597,13 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     // show.
     facets.activeFilters === 0 &&
     ranges.length === 0 &&
-    state.category === undefined &&
+    // A category pane the surface turned off is not a control on this rail,
+    // however narrowed the search is: the way back out of a leaf is then the
+    // breadcrumb or the tiles above, not a filter (`categoryFilter`).
+    (props.categoryFilter === false ||
+      (state.category === undefined &&
+        props.renderCategoryFilter === undefined)) &&
     state.lang === undefined &&
-    props.renderCategoryFilter === undefined &&
     (props.languages ?? []).length === 0;
   const showFilters = filtersHeader !== undefined || !filtersEmpty;
 
@@ -616,6 +649,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           {...(props.renderCategoryFilter !== undefined
             ? { renderCategoryFilter: props.renderCategoryFilter }
             : {})}
+          {...(props.categoryFilter !== undefined
+            ? { categoryFilter: props.categoryFilter }
+            : {})}
           {...(props.skippedNotice !== undefined
             ? { skippedNotice: props.skippedNotice }
             : {})}
@@ -661,6 +697,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const results = (
     <SearchResultsPane
       toolbar={toolbar}
+      {...(props.resultsLead !== undefined ? { lead: props.resultsLead } : {})}
       {...(phoneToolbar ? { header: "compact" as const } : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
@@ -776,7 +813,8 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             /* The catalogue picker becomes the row's leading chip. The panel
                behind the circle keeps its own copy of the control; both write
                the same `category` parameter, so they cannot disagree. */
-            {...(props.renderCategoryFilter !== undefined
+            {...(props.renderCategoryFilter !== undefined &&
+            props.categoryFilter !== false
               ? { renderCategoryFilter: props.renderCategoryFilter }
               : {})}
             {...(props.categoryLabel !== undefined
@@ -853,6 +891,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     footer,
     filtersHeader,
     resultsHeader,
+    resultsLead,
+    categoryFilter,
     appliedChips,
     otherCategories,
     categoryName,
@@ -895,6 +935,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(footer !== undefined ? { footer } : {})}
           {...(filtersHeader !== undefined ? { filtersHeader } : {})}
           {...(resultsHeader !== undefined ? { resultsHeader } : {})}
+          {...(resultsLead !== undefined ? { resultsLead } : {})}
+          {...(categoryFilter !== undefined ? { categoryFilter } : {})}
           {...(appliedChips !== undefined ? { appliedChips } : {})}
           {...(otherCategories !== undefined ? { otherCategories } : {})}
           {...(categoryName !== undefined ? { categoryName } : {})}

package/src/default/SearchResultsPane.tsx

@@ -180,6 +180,16 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * toolbar in here instead of printing a second caption above the pane.
    */
   readonly toolbar?: ReactNode;
+  /**
+   * The very top of the pane, ABOVE the heading row and its toolbar.
+   *
+   * For whatever describes THIS LIST and is not one of its controls: a
+   * category's own introduction, a promoted band, a "12 new since yesterday"
+   * line. It is inside the results column, which is the difference between
+   * this and `<SearchPage resultsHeader>` — that one spans both columns and
+   * would put the same block over the filter rail as well.
+   */
+  readonly lead?: ReactNode;
   /**
    * What this list is CALLED on this surface. Default: "Results".
    *
@@ -363,6 +373,9 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
       <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
         {(bag) => (
           <Flex vertical gap={spacing[4]}>
+            {props.lead !== undefined && (
+              <div data-testid="search-results-lead">{props.lead}</div>
+            )}
             {props.header === "compact" ? (
               <Flex vertical gap={spacing[2]} data-testid="search-results-header-compact">
                 <Typography.Title

package/src/default/SortSelect.tsx

@@ -52,17 +52,17 @@ export interface SortSelectProps {
    *  - the {@link SORT_SELECT_MIN_WIDTH} floor goes, so the control shares one
    *    row with whatever the surface puts beside it instead of pushing it to
    *    the next line;
-   *  - the blocked option's REASON moves from a line under the control into
-   *    the option's own label.
+   *  - the line under the control goes. The blocked option's REASON does not:
+   *    it is on the option itself at every width now (see `optionsFor`), and
+   *    what the compact form drops is the second, separate copy of it.
    *
-   * That last move is not the reason being dropped. This file exists because
-   * the reason used to live in a `title=` a phone can never surface, and a
-   * phone is exactly where "sort by distance" is greyed out most often. On a
-   * 390px toolbar the reason as a separate row costs a whole band of the
-   * viewport above the first result — so it goes where the person actually
-   * meets the refusal: on the disabled row of the open list, which a screen
-   * reader reads out with the option and a thumb reads at the moment of the
-   * tap. Nothing is hidden; it is closer to the thing it explains.
+   * The reason lives on the row because that is where the person meets the
+   * refusal — a disabled row of the open list, which a screen reader reads out
+   * with the option and a thumb reads at the moment of the tap. This file
+   * exists because it used to live in a `title=` a phone can never surface,
+   * and a phone is exactly where "sort by distance" is greyed out most often;
+   * on a 390px toolbar the reason as a separate row would also cost a whole
+   * band of the viewport above the first result.
    */
   readonly compact?: boolean;
 }
@@ -94,7 +94,23 @@ export function SortSelect(props: SortSelectProps): ReactElement {
     ? actionAvailable()
     : actionBlocked(SORT_DISTANCE_BLOCKED);
 
-  const optionsFor = (describedBy?: string): {
+  /**
+   * The list, with the blocked row carrying its own reason — AT EVERY WIDTH.
+   *
+   * This used to be the compact arm's alone. The desktop arm relied on
+   * `GatedControl`'s sentence beside the closed select, which is where a
+   * screen reader meets it (`aria-describedby`) and is NOT where a person
+   * meets the refusal: they open the list, find one row greyed out, and the
+   * explanation for it is behind the open dropdown, above a control the
+   * dropdown is covering. A greyed row with no reason on it is the same defect
+   * this file was written to fix, one width up — it was a `title=` then and a
+   * line the dropdown hides now.
+   *
+   * So the row says it, and the sentence beside the control stays: one is the
+   * accessible description of the SELECT, the other is the label of the OPTION
+   * that is refused, and they are read in different moments.
+   */
+  const optionsFor = (): {
     readonly value: string;
     readonly label: string;
     readonly disabled: boolean;
@@ -105,13 +121,7 @@ export function SortSelect(props: SortSelectProps): ReactElement {
       const blocked = value === "distance" && !hasCentre;
       return {
         value,
-        // In the compact form the option carries its own reason — see
-        // `SortSelectProps.compact`. Elsewhere `GatedControl` renders it once,
-        // beside the control, and repeating it here would say it twice.
-        label:
-          blocked && props.compact === true && describedBy === undefined
-            ? `${label} — ${t(SORT_DISTANCE_BLOCKED)}`
-            : label,
+        label: blocked ? `${label} — ${t(SORT_DISTANCE_BLOCKED)}` : label,
         disabled: blocked,
       };
     });
@@ -153,7 +163,7 @@ export function SortSelect(props: SortSelectProps): ReactElement {
             onChange={(next) => {
               setSort(next);
             }}
-            options={optionsFor(bind["aria-describedby"] ?? "")}
+            options={optionsFor()}
           />
         </Flex>
       )}

package/src/default/index.ts

@@ -74,6 +74,7 @@ export {
   CHIP_BAND_ORDER,
   CHIP_ROW_CAP,
   CHIP_ROW_CLASS,
+  CHIP_ROW_MIN_HEIGHT,
   CHIP_ROW_STYLE_HREF,
   appliedChipTestId,
   buildAppliedChips,
@@ -103,6 +104,7 @@ export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";
 
 export {
   FacetGroupControl,
+  facetGroupIsEmptyHeading,
   facetGroupShape,
   facetOptionNodes,
   isDictionaryFacet,
@@ -122,8 +124,13 @@ export type {
 export {
   PopularValues,
   popularOptions,
+  popularValuesLadderCss,
+  POPULAR_VALUES_CLASS,
   POPULAR_VALUES_COLUMNS,
+  POPULAR_VALUES_LADDER,
   POPULAR_VALUES_LIMIT,
+  POPULAR_VALUES_STYLE_HREF,
+  POPULAR_VALUE_COLUMN_WIDTH,
 } from "./PopularValues.js";
 export type { PopularValuesProps } from "./PopularValues.js";
 export { PartitionChips } from "./PartitionChips.js";
@@ -166,7 +173,7 @@ export type {
 } from "./DegradationNotice.js";
 export { UrlIssueNotice } from "./UrlIssueNotice.js";
 export { RangeFilterRow } from "./RangeFilterRow.js";
-export type { RangeFilterRowProps } from "./RangeFilterRow.js";
+export type { RangeDraft, RangeFilterRowProps } from "./RangeFilterRow.js";
 
 // ── theming ─────────────────────────────────────────────────────────────────
 export type { ThemeModeProp } from "./types.js";

package/src/headless/FacetPanel.tsx

@@ -127,6 +127,13 @@ export interface FacetPanelBag {
    */
   setValues(slug: string, values: readonly string[]): void;
   setRange(slug: string, range: SearchRange | null): void;
+  /**
+   * Write several ranges in ONE commit — see
+   * {@link SearchStateBag.setRanges}. What the panel's single "Apply"
+   * calls: `setRange` twice in a tick applies the second axis and drops the
+   * first, because both edits fold into the same starting state.
+   */
+  setRanges(ranges: Readonly<Record<string, SearchRange | null>>): void;
   clear(slug: string): void;
   clearAll(): void;
 }
@@ -206,8 +213,15 @@ export function useFacetPanel(props: {
    */
   resolveFacetLabels?: FacetLabelResolver;
 } = {}): FacetPanelBag {
-  const { state: searchState, setFilter, setRange, clearAll, toggleFilter, activeFilters } =
-    useSearchState();
+  const {
+    state: searchState,
+    setFilter,
+    setRange,
+    setRanges,
+    clearAll,
+    toggleFilter,
+    activeFilters,
+  } = useSearchState();
   const t = useT();
   const query = useSearchQuery(
     searchState,
@@ -285,6 +299,7 @@ export function useFacetPanel(props: {
     toggle: toggleFilter,
     setValues: setFilter,
     setRange,
+    setRanges,
     clear: (slug) => {
       setFilter(slug, []);
     },

package/src/headless/SearchStateProvider.tsx

@@ -168,6 +168,21 @@ export interface SearchStateBag {
   toggleFilter(slug: string, value: string): void;
   setFilter(slug: string, values: readonly string[]): void;
   setRange(slug: string, range: SearchRange | null): void;
+  /**
+   * Write SEVERAL ranges at once — the bulk half of {@link setRange}, and the
+   * same relationship `setFilter` has to `toggleFilter`.
+   *
+   * Every setter here closes over the state it edits, so two of them in one
+   * tick both fold their change into the SAME starting value and the second
+   * one wins. That is invisible while one control writes one axis; it is the
+   * whole story for a filter panel with one "Apply" over a price row and
+   * a mileage row, where two calls would have applied the mileage and quietly
+   * dropped the price. This folds them all into one state and commits once —
+   * one request, one history entry.
+   *
+   * `null` for a slug clears it, exactly as it does on {@link setRange}.
+   */
+  setRanges(ranges: Readonly<Record<string, SearchRange | null>>): void;
   setGeo(geo: SearchGeo | null): void;
   setLimit(limit: number | null): void;
   clearAll(): void;
@@ -506,6 +521,14 @@ export function SearchStateProvider(
         apply(setFilterValues(state, slug, values), historyOptions("filter")),
       setRange: (slug, range) =>
         apply(setRangeValue(state, slug, range), historyOptions("range")),
+      setRanges: (ranges) =>
+        apply(
+          Object.entries(ranges).reduce(
+            (next, [slug, range]) => setRangeValue(next, slug, range),
+            state
+          ),
+          historyOptions("range")
+        ),
       setGeo: (geo) => {
         apply(patchSearchState(state, { geo }), historyOptions("geo"));
       },

package/src/index.ts

@@ -49,16 +49,21 @@ export {
   SUGGEST_DEGRADED_CATEGORIES,
   SUGGEST_DEGRADED_ROLLUP,
   suggestTerms,
+  withheldSlugs,
 } from "./api/types.js";
 export type {
+  FacetAxisKind,
   FacetCategoryCount,
   FacetLabels,
   FacetLabelsMap,
   FacetMeta,
+  FacetRangeAxis,
   FacetRangeBounds,
   FacetRangesMap,
   FacetSelection,
+  FacetWithheldAxis,
   FacetWithheldGroup,
+  FacetWithheldReason,
   RankingResponse,
   Scorer,
   SearchDegradation,
@@ -156,6 +161,9 @@ export {
 } from "./state/ranges.js";
 export type { BuildRangeGroupsInput, RangeGroup } from "./state/ranges.js";
 
+export { orderPanelItems } from "./state/panel.js";
+export type { OrderPanelItemsInput, PanelItem } from "./state/panel.js";
+
 export {
   SEARCH_BOX_DEBOUNCE_MS,
   SEARCH_BOX_SUGGEST_DEBOUNCE_MS,

package/src/state/facets.ts

@@ -239,6 +239,19 @@ export interface FacetGroup {
    * hold. `undefined` means nobody said, not "inline".
    */
   readonly vocabulary?: string;
+  /**
+   * Where this group sits in the ONE sequence the panel draws — the answer's
+   * `facet_labels[<slug>].order`, numbered together with the numeric axes'
+   * `facet_meta.ranges[<slug>].order` (stapel-search 0.16.0+).
+   *
+   * The point of the field is that a group and a range are two ways of
+   * narrowing one authored feature, so they share a scale: drawn sorted by it,
+   * "Price" and "Year" land among the makes and models instead of above and
+   * below all of them. `undefined` (an older server, or a group the plan has
+   * no place for, which the wire says as `null`) means "no stated position",
+   * and `orderPanelItems` sorts those after everything that has one.
+   */
+  readonly order?: number | undefined;
   /** The group's heading: the answer's own `label`, else the feature's
    * display name, else — with a dev warning — the raw slug. */
   readonly label: string;
@@ -606,6 +619,19 @@ function optionalVocabulary(
   return vocabulary === undefined ? {} : { vocabulary };
 }
 
+/**
+ * The group's stated place in the panel, when the answer states one.
+ *
+ * `null` on the wire is the server's own "the plan has no position for this
+ * group", which reads exactly like a server too old to state one: both mean
+ * "sort me after everything that does have a place". So both spread to
+ * nothing, and `FacetGroup.order` is a number or absent — never a `null` a
+ * comparator would have to remember to special-case.
+ */
+function optionalOrder(order: number | null | undefined): { order?: number } {
+  return typeof order === "number" ? { order } : {};
+}
+
 function resolveVocabulary(
   input: BuildFacetGroupsInput,
   feature: FeatureDef | undefined,
@@ -813,6 +839,7 @@ export function buildFacetGroups(input: BuildFacetGroupsInput): readonly FacetGr
     return {
       slug,
       urlKey: keys.write[slug] ?? slug,
+      ...optionalOrder(input.facetLabels?.[slug]?.order),
       ...optionalVocabulary(resolveVocabulary(input, feature, slug)),
       ...resolveGroupLabel(input, feature, slug),
       feature,