@stapel/search-react 0.31.0 → 0.32.1

package/src/default/PopularValues.tsx

@@ -29,7 +29,7 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Button, Flex, Typography } from "antd";
 import { useT } from "@stapel/core";
-import { spacing } from "@stapel/tokens";
+import { breakpoints, spacing } from "@stapel/tokens";
 import type { FacetGroup, FacetOption } from "../state/facets.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
@@ -40,6 +40,66 @@ export const POPULAR_VALUES_LIMIT = 12;
  * without turning a make into a two-line wrap. */
 export const POPULAR_VALUES_COLUMNS = 3;
 
+/**
+ * The width one column of this block needs: a make and its count, on one line,
+ * at the default type step. «Ford 1 204» is the measure; below it a value
+ * wraps under its own number and the block stops being scannable.
+ */
+export const POPULAR_VALUE_COLUMN_WIDTH = 200;
+
+/** The class the container query is hung on. */
+export const POPULAR_VALUES_CLASS = "stapel-popular-values";
+
+/** The `href` the hoisted ladder sheet is deduplicated by (React 19). */
+export const POPULAR_VALUES_STYLE_HREF = "stapel-popular-values";
+
+/**
+ * The ladder `columns="responsive"` climbs — one rung per column, by the width
+ * of the BLOCK rather than of the window.
+ *
+ * The container is what decides, and it has to be: this block sits in the
+ * results column, which on a 1440px desktop is the window minus a 280px rail
+ * minus the gap. A media query would give it four columns at a width it never
+ * has, and one column inside a narrow host container that happens to sit on a
+ * wide screen. `container-type: inline-size` plus `@container` asks the only
+ * question that has an answer here — how wide is this block.
+ *
+ * The rungs: one column while the block is narrower than two of
+ * {@link POPULAR_VALUE_COLUMN_WIDTH}, then the two token breakpoints for the
+ * third and fourth. `tablet` and `desktop` are `@stapel/tokens`' own numbers,
+ * and using them here is the same statement they make everywhere else — this
+ * is where a layout of this density gains a column.
+ */
+export const POPULAR_VALUES_LADDER: readonly {
+  readonly minInlineSize: number;
+  readonly columns: number;
+}[] = [
+  { minInlineSize: POPULAR_VALUE_COLUMN_WIDTH * 2, columns: 2 },
+  { minInlineSize: breakpoints.tablet, columns: 3 },
+  { minInlineSize: breakpoints.desktop, columns: 4 },
+];
+
+/**
+ * The ladder as CSS. One `@container` rule per rung, ascending, so the widest
+ * matching rung is the one that wins by ordinary cascade order.
+ *
+ * Emitted as a hoisted `<style>` rather than an inline style because a
+ * container query is unreachable from one — the same reason `<SearchPage>`
+ * hoists its rail sheet.
+ */
+export function popularValuesLadderCss(): string {
+  const block = `.${POPULAR_VALUES_CLASS}`;
+  return [
+    `${block}{container-type:inline-size}`,
+    `${block}>[data-popular-columns]{column-count:1}`,
+    ...POPULAR_VALUES_LADDER.map(
+      (rung) =>
+        `@container (min-width: ${String(rung.minInlineSize)}px)` +
+        `{${block}>[data-popular-columns]{column-count:${String(rung.columns)}}}`
+    ),
+  ].join("\n");
+}
+
 /** A value with no evidence behind it is not a popular value. Uncounted
  * options carry `count: null` and are dropped here rather than printed with a
  * blank where the number belongs — the block IS the numbers. */
@@ -76,8 +136,15 @@ export interface PopularValuesProps {
   readonly hidden?: boolean;
   /** How many values. Default {@link POPULAR_VALUES_LIMIT}. */
   readonly limit?: number;
-  /** How many columns. Default {@link POPULAR_VALUES_COLUMNS}. */
-  readonly columns?: number;
+  /**
+   * How many columns. Default {@link POPULAR_VALUES_COLUMNS}.
+   *
+   * `"responsive"` climbs {@link POPULAR_VALUES_LADDER} by the width of the
+   * BLOCK — 1, 2, 3, 4 — instead of taking one number for every surface. The
+   * numeric form stays, and stays the default: a host that has already decided
+   * its layout should not have that decision taken back by a query.
+   */
+  readonly columns?: number | "responsive";
   /** The block's heading. Defaults to the group's own label; `null` draws
    * none, for a surface that has already named the axis. */
   readonly heading?: ReactNode;
@@ -93,19 +160,36 @@ export function PopularValues(props: PopularValuesProps): ReactElement | null {
   const options = popularOptions(group, props.limit ?? POPULAR_VALUES_LIMIT);
   if (options.length === 0) return null;
 
+  const responsive = props.columns === "responsive";
+
   return (
     <Flex
       vertical
       gap={spacing[2]}
+      {...(responsive ? { className: POPULAR_VALUES_CLASS } : {})}
       data-testid={`popular-values-${group.slug}`}
       data-label-source={group.labelSource}
+      data-columns={responsive ? "responsive" : String(props.columns ?? POPULAR_VALUES_COLUMNS)}
     >
+      {/* The ladder, hoisted and deduped by `href`: a container query has no
+          inline form. Only where it is asked for — a block with a fixed
+          column count needs no sheet at all. */}
+      {responsive && (
+        <style href={POPULAR_VALUES_STYLE_HREF} precedence="default">
+          {popularValuesLadderCss()}
+        </style>
+      )}
       {props.heading !== null && (
         <Typography.Text strong>{props.heading ?? group.label}</Typography.Text>
       )}
       <div
+        {...(responsive ? { "data-popular-columns": "" } : {})}
         style={{
-          columnCount: props.columns ?? POPULAR_VALUES_COLUMNS,
+          // The rungs live in the sheet above; an inline `column-count` here
+          // would win against every one of them.
+          ...(responsive
+            ? {}
+            : { columnCount: props.columns ?? POPULAR_VALUES_COLUMNS }),
           columnGap: spacing[4],
         }}
       >

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, []);
     },