@stapel/search-react 0.36.1 → 0.38.0

package/src/default/SearchPage.tsx

@@ -66,7 +66,7 @@ import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Button, Flex } from "antd";
 import { SkinDialog, SkinTheme, useDialogSurface } from "@stapel/tokens-antd/skin";
 import { useT, useTPlural } from "@stapel/core";
-import { cssVar, spacing } from "@stapel/tokens";
+import { breakpoints, cssVar, spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import { SearchStateProvider, useSearchState } from "../headless/SearchStateProvider.js";
 import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
@@ -261,47 +261,89 @@ export const FILTERS_RAIL_WIDTH = 280;
  * `alignSelf: flex-start` is load-bearing: a flex child stretches to the row's
  * height by default, and a stretched box has nothing to stick to.
  */
-/** The class the rail's own scrollbar rules are hung on. */
+/** The class the rail's own geometry and scrollbar rules are hung on. */
 export const RAIL_CLASS = "stapel-search-rail";
 
+/**
+ * The class that carries the SKIN's scrollbar — present under
+ * `railScrollbar: "styled"` and absent under `"system"`, so the two arms are
+ * one class apart and a stand can read which one is on screen.
+ */
+export const RAIL_SCROLLBAR_CLASS = "stapel-search-rail-scrollbar";
+
 /** The `href` the hoisted rail sheet is deduplicated by. */
 export const RAIL_STYLE_HREF = "stapel-search-rail";
 
+/** Whose scrollbar the rail's own scroll port draws — see
+ * {@link SearchPageProps.railScrollbar}. */
+export type SearchRailScrollbar = "styled" | "system";
+
 /**
- * The rail scrolls, and its scrollbar must not sit ON the filters.
+ * The scrollbar's track width, in CSS pixels.
  *
- * `scrollbar-width: thin` and `scrollbar-gutter: stable` (below, in `RAIL`)
- * are the standard half of this and they are not enough: on every WebKit
- * platform with overlay scrollbars — a Mac by default, every iOS browser —
- * the bar is drawn OVER the content and the gutter reserves nothing, so the
- * walker saw the bar lying across the right edge of the checkbox labels.
+ * Not on the spacing scale on purpose, and not a spacing decision: this is the
+ * thickness of a hairline instrument, the size every platform's own overlay
+ * bar lands within, and the number the storefront's owner named. Six is thin
+ * enough to read as part of the panel and thick enough to grab.
+ */
+const RAIL_SCROLLBAR_WIDTH = 6;
+
+/**
+ * The rail scrolls, and the bar that says so is the SKIN's, not the platform's.
+ *
+ * The system bar was never a decision — it is what an `overflow-y: auto` box
+ * gets when nobody says otherwise, and on the storefront it landed as a grey
+ * chrome-coloured strip standing next to the filters in a dark theme. What it
+ * is replaced with:
+ *
+ *  - a 6px track with no arrows and no track fill — the rail's own hairline,
+ *    not a widget;
+ *  - a thumb that is TRANSPARENT at rest and appears on `:hover` of the rail
+ *    (which is what a pointer scrolling inside it is doing) and on
+ *    `:focus-within` (which is what a keyboard is doing). A coarse pointer
+ *    fires neither, so under `(pointer: coarse)` the thumb stands — a touch
+ *    surface with an invisible scrollbar is a rail with no sign it has a tail;
+ *  - `scrollbar-gutter: stable`, so the panel's right edge does not move when
+ *    the thumb arrives.
  *
- * So the rail also declares a CLASSIC scrollbar through the WebKit
- * pseudo-elements: a bar with a real width, which pushes the panel's content
- * in by exactly that much instead of floating above it, drawn in the token
- * palette so it is the panel's own hairline in both themes rather than a
- * hard-coded grey that glows in the dark one. `--stapel-*` custom properties
- * resolve per theme at paint time, which is why this is a sheet and not a
- * pair of computed inline values: an inline colour would freeze whichever
- * theme was mounted first.
+ * Both vendor forms, because they are not alternatives: Firefox reads
+ * `scrollbar-width`/`scrollbar-color` and nothing else, WebKit and Chromium
+ * read the `::-webkit-scrollbar` pseudo-elements and (in Chromium) the
+ * standard properties too.
+ *
+ * The colours are `--stapel-*` custom properties, which resolve per theme at
+ * paint time — an inline colour or a `useToken()` value would freeze whichever
+ * theme was mounted first. This design system's neutral vocabulary has no
+ * `colorFill*` ramp of its own: `border` IS its tertiary-fill role (the
+ * hairline every pane is separated by) and `text-subtle` is that role one step
+ * stronger, which is what the thumb takes when a pointer is on the thumb
+ * itself.
  *
  * Emitted as one hoisted `<style>` (React 19 dedupes by `href`), because a
  * pseudo-element is unreachable from an inline style — the same reason
  * `<LocationSummaryLine>` hoists one.
  */
 export function railScrollbarCss(): string {
-  const rail = `.${RAIL_CLASS}`;
+  const bar = `.${RAIL_SCROLLBAR_CLASS}`;
+  const size = `${String(RAIL_SCROLLBAR_WIDTH)}px`;
+  const thumb = cssVar("border");
+  const awake = `${bar}:hover,${bar}:focus-within`;
   return [
-    // A real width: an overlay bar occupies no space and therefore overlaps.
-    `${rail}::-webkit-scrollbar{inline-size:8px;block-size:8px}`,
-    `${rail}::-webkit-scrollbar-track{background:transparent}`,
-    `${rail}::-webkit-scrollbar-thumb{background:${cssVar("border")};` +
+    // ── Firefox ────────────────────────────────────────────────────────────
+    `${bar}{scrollbar-width:thin;scrollbar-gutter:stable;` +
+      `scrollbar-color:transparent transparent}`,
+    `${awake}{scrollbar-color:${thumb} transparent}`,
+    // ── WebKit / Chromium ──────────────────────────────────────────────────
+    `${bar}::-webkit-scrollbar{inline-size:${size};block-size:${size}}`,
+    `${bar}::-webkit-scrollbar-track{background:transparent}`,
+    `${bar}::-webkit-scrollbar-thumb{background:transparent;` +
       `border-radius:${cssVar("radius-full")}}`,
-    `${rail}::-webkit-scrollbar-thumb:hover{background:${cssVar("text-subtle")}}`,
-    // Firefox/Chromium's standard properties, stated here too so the rule
-    // travels with the class when the panel is used outside `<SearchPage>`.
-    `${rail}{scrollbar-width:thin;scrollbar-gutter:stable;` +
-      `scrollbar-color:${cssVar("border")} transparent}`,
+    `${bar}:hover::-webkit-scrollbar-thumb,` +
+      `${bar}:focus-within::-webkit-scrollbar-thumb{background:${thumb}}`,
+    `${bar}::-webkit-scrollbar-thumb:hover{background:${cssVar("text-subtle")}}`,
+    // ── A surface with no hover at all ─────────────────────────────────────
+    `@media (pointer:coarse){${bar}{scrollbar-color:${thumb} transparent}` +
+      `${bar}::-webkit-scrollbar-thumb{background:${thumb}}}`,
   ].join("\n");
 }
 
@@ -320,14 +362,11 @@ const RAIL: CSSProperties = {
   maxHeight: "100dvh",
   overflowY: "auto",
   overscrollBehavior: "contain",
-  // The inner scroll must be VISIBLE. On overlay-scrollbar platforms (every
-  // Mac by default, most phones) an `overflow-y: auto` column shows no
-  // scrollbar until a pointer happens to scroll INSIDE it — so a rail taller
-  // than the window is indistinguishable from a rail that ends at the fold,
-  // and the walker measured 5717px of panel whose tail nothing signposted.
-  // A thin, always-there scrollbar is the sign there is more; the stable
-  // gutter keeps the panel's right edge from jumping when it appears.
-  scrollbarWidth: "thin",
+  // The gutter is the rail's, whichever bar draws in it: reserved here so the
+  // panel's right edge does not move when the thumb arrives. The bar's own
+  // width and colour are the skin's and live in `railScrollbarCss` — a rule
+  // set, not an inline pair, because a thumb that appears on hover cannot be
+  // said in a style attribute.
   scrollbarGutter: "stable",
   // Room for the focus ring of the last control against the scroll edge.
   paddingBlockEnd: spacing[2],
@@ -355,6 +394,71 @@ export function railStyle(top: number | string | undefined): CSSProperties {
  * cannot push the grid wider than its column. */
 const RESULTS_COLUMN: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
 
+/* ── THE RHYTHM: ONE GAP BETWEEN BLOCKS, SAID ONCE ─────────────────────────
+ *
+ * This page is an assembly of BLOCKS — the query box, the breadcrumb, the
+ * location row, the header band, the applied chips, the columns — and every
+ * gap between two of them used to be `spacing[4]` on the root plus whatever
+ * outer margin the block itself happened to carry. Sixteen pixels is what a
+ * form's fields are spaced by, not what a page's sections are: on the walked
+ * storefront the blocks read as one undifferentiated column, and the owner's
+ * word for it was that everything is stuck together.
+ *
+ * The gap is now ONE PAIR of custom properties, declared as a usage and not as
+ * a definition — `var(--stapel-block-gap, 32px)`. That is the whole point of
+ * the shape: a host (or a container's own stylesheet, or a brand) sets the
+ * property anywhere above this page and every block on it moves together,
+ * while a host that sets nothing gets the design system's own spacing step.
+ *
+ * The compact value is for a COARSE POINTER or a narrow window, in one query
+ * with two arms: a phone has less height to spend on air, and a tablet held in
+ * a hand is a phone for this purpose whatever its width says.
+ *
+ * The names are the pair's published contract, which is why they are exported:
+ * `categories-react`'s pages declare the same two, so a storefront that tunes
+ * the rhythm tunes BOTH pairs with one declaration.
+ */
+
+/** The custom property every block gap on this page reads. */
+export const BLOCK_GAP_VAR = "--stapel-block-gap";
+
+/** Its coarse-pointer / narrow-window twin. */
+export const BLOCK_GAP_COMPACT_VAR = "--stapel-block-gap-compact";
+
+/** The class the rhythm's rules are hung on. */
+export const BLOCK_RHYTHM_CLASS = "stapel-block-rhythm";
+
+/** The `href` the hoisted rhythm sheet is deduplicated by. */
+export const BLOCK_RHYTHM_STYLE_HREF = "stapel-block-rhythm";
+
+/** Where the page's block gap comes from — see
+ * {@link SearchPageProps.blockRhythm}. */
+export type SearchBlockRhythm = "token" | "legacy";
+
+/**
+ * The rhythm's rule set.
+ *
+ * Three rules, and the third is half of the fix: `margin-block: 0` on every
+ * direct child. A gap only governs the space a container puts BETWEEN its
+ * children — a block that also carries its own top or bottom margin adds to it
+ * and the spacing stops being one number, which is exactly how a page ends up
+ * with four different distances nobody chose.
+ *
+ * A sheet rather than inline styles because the compact arm is a media query
+ * and the reset addresses children this component does not own.
+ */
+export function blockRhythmCss(): string {
+  const block = `.${BLOCK_RHYTHM_CLASS}`;
+  const narrow = `(max-width:${String(breakpoints.tablet - 1)}px)`;
+  return [
+    `${block}{gap:var(${BLOCK_GAP_VAR},${String(spacing[6])}px)}`,
+    `@media (pointer:coarse),${narrow}{` +
+      `${block}{gap:var(${BLOCK_GAP_COMPACT_VAR},${String(spacing[5])}px)}}`,
+    // A block's own outer margin is a second opinion about the same distance.
+    `${block}>*{margin-block:0}`,
+  ].join("\n");
+}
+
 export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions {
   /** The URL binding. `useRouterSearchParams()` from `./router` is the
    * react-router one. */
@@ -659,6 +763,46 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * header to clear.
    */
   readonly railTop?: number | string;
+  /**
+   * WHOSE SCROLLBAR the rail's own scroll port draws. Default `"styled"`.
+   *
+   * The rail is a scroll container and stays one: a person who has scrolled
+   * the filters and ticked one does not want the page to have moved under
+   * them. What it stopped drawing is the PLATFORM's bar — a grey chrome strip
+   * beside the filters, which is what an `overflow-y: auto` box gets when
+   * nobody decides otherwise.
+   *
+   *  - `"styled"` — the skin's own bar, from the tokens, in both themes: a 6px
+   *    track, no arrows, no track fill, and a thumb that is transparent at
+   *    rest and appears while the rail is hovered or focused within (always,
+   *    on a coarse pointer that can do neither). See {@link railScrollbarCss};
+   *  - `"system"` — the platform's, untouched, for a host whose own stylesheet
+   *    already dresses every scroll port on the page and would then be
+   *    dressing this one twice.
+   *
+   * The default is the NEW behaviour, deliberately: the system bar was never a
+   * design decision here — it was the absence of one, and it is the thing the
+   * page was measured on.
+   */
+  readonly railScrollbar?: SearchRailScrollbar;
+  /**
+   * WHERE the space between this page's blocks comes from. Default `"token"`.
+   *
+   *  - `"token"` — one gap for every block, read from
+   *    `var(--stapel-block-gap)` (and `var(--stapel-block-gap-compact)` on a
+   *    coarse pointer or a narrow window), defaulting to the design system's
+   *    own spacing steps. Every direct block also has its outer margin reset,
+   *    so the distance between two blocks is ONE number and a host can retune
+   *    all of them by declaring the property once — see {@link blockRhythmCss};
+   *  - `"legacy"` — the flat `spacing[4]` this page wrote inline for a host
+   *    whose own layout was measured against it.
+   *
+   * The default is the NEW behaviour: 16px between a page's sections was the
+   * value a vertical `<Flex>` was given when the page was first assembled, not
+   * a rhythm anybody chose, and it is what made the blocks read as one column
+   * with no seams.
+   */
+  readonly blockRhythm?: SearchBlockRhythm;
   /**
    * PIN the results toolbar under whatever chrome is above this page — the
    * other column's half of {@link railTop}.
@@ -793,6 +937,13 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * grid it could not read back.
    */
   readonly resultsColumns?: ResultsColumns;
+  /**
+   * The box the results arrive into — `<SearchResultsPane reserve>`,
+   * forwarded. Here for the same reason `resultsColumns` is: the page is what
+   * a storefront mounts, and this was the last thing on it a host could only
+   * reach with `#search-page > :last-child` in its own stylesheet.
+   */
+  readonly resultsReserve?: number | string;
   /**
    * Is the results caption SEEN below the sheet breakpoint —
    * `<SearchResultsPane headingVisible>`, forwarded. Default: the host's own
@@ -804,6 +955,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
   readonly resultsColumns?: ResultsColumns;
+  readonly resultsReserve?: number | string;
   readonly resultsHeadingVisible?: boolean;
   readonly categoryFilter?: boolean;
   readonly resultsLead?: ReactNode;
@@ -837,6 +989,8 @@ interface SearchPageBodyProps {
   readonly railFrom?: SearchRailFrom;
   readonly filtersLayout?: SearchFiltersLayout;
   readonly railTop?: number | string;
+  readonly railScrollbar?: SearchRailScrollbar;
+  readonly blockRhythm?: SearchBlockRhythm;
   readonly stickyToolbar?: SearchToolbarPin;
   readonly defaultFiltersOpen?: boolean;
   readonly filtersOpen?: boolean;
@@ -1112,6 +1266,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(props.resultsColumns !== undefined
         ? { columns: props.resultsColumns }
         : {})}
+      {...(props.resultsReserve !== undefined
+        ? { reserve: props.resultsReserve }
+        : {})}
       {...(props.resultsHeadingVisible !== undefined
         ? { headingVisible: props.resultsHeadingVisible }
         : {})}
@@ -1141,14 +1298,28 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     />
   );
 
+  const legacyRhythm = props.blockRhythm === "legacy";
   return (
     <Flex
       vertical
-      gap={spacing[4]}
+      // ONE gap for every block on this page, from the token pair — or the
+      // 16px this page used to state inline, for a host pinned to it.
+      {...(legacyRhythm
+        ? { gap: spacing[4] }
+        : { className: BLOCK_RHYTHM_CLASS })}
       data-testid="search-page"
+      data-rhythm={legacyRhythm ? "legacy" : "token"}
       data-filters={showFilters ? "on" : "off"}
       data-filters-layout={layout}
     >
+      {/* The rhythm's rules — see `blockRhythmCss`. Hoisted, deduped by
+          `href`, and not mounted at all when the host asked for the old
+          inline gap. */}
+      {!legacyRhythm && (
+        <style href={BLOCK_RHYTHM_STYLE_HREF} precedence="default">
+          {blockRhythmCss()}
+        </style>
+      )}
       {props.searchBox !== false && <SearchBox />}
       {props.breadcrumb !== undefined && (
         <div data-testid="search-breadcrumb">{props.breadcrumb}</div>
@@ -1264,12 +1435,23 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         </>
       ) : showFilters ? (
         <Flex align="flex-start" gap={spacing[5]} data-testid="search-page-columns">
-          <div className={RAIL_CLASS} style={railStyle(props.railTop)}>
+          <div
+            className={
+              props.railScrollbar === "system"
+                ? RAIL_CLASS
+                : `${RAIL_CLASS} ${RAIL_SCROLLBAR_CLASS}`
+            }
+            style={railStyle(props.railTop)}
+          >
             {/* The rail's scrollbar, in the gutter and in the token palette —
-                see `railScrollbarCss`. Hoisted, deduped by `href`. */}
-            <style href={RAIL_STYLE_HREF} precedence="default">
-              {railScrollbarCss()}
-            </style>
+                see `railScrollbarCss`. Hoisted, deduped by `href`. Not mounted
+                at all under `"system"`: a sheet whose only selector is a class
+                nothing carries is dead weight in the document. */}
+            {props.railScrollbar !== "system" && (
+              <style href={RAIL_STYLE_HREF} precedence="default">
+                {railScrollbarCss()}
+              </style>
+            )}
             {panel}
           </div>
           {/* ONE heading and ONE sort control. The page used to caption
@@ -1319,6 +1501,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     railFrom,
     filtersLayout,
     railTop,
+    railScrollbar,
+    blockRhythm,
     stickyToolbar,
     defaultFiltersOpen,
     filtersOpen,
@@ -1332,6 +1516,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     resultsAction,
     resultsHeadingLevel,
     resultsColumns,
+    resultsReserve,
     resultsHeadingVisible,
     dictionaryMode,
     visibleGroups,
@@ -1347,6 +1532,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
         <SearchPageBody
           {...(renderCard !== undefined ? { renderCard } : {})}
           {...(resultsColumns !== undefined ? { resultsColumns } : {})}
+          {...(resultsReserve !== undefined ? { resultsReserve } : {})}
           {...(resultsHeadingVisible !== undefined ? { resultsHeadingVisible } : {})}
           {...(dictionaryMode !== undefined ? { dictionaryMode } : {})}
           {...(visibleGroups !== undefined ? { visibleGroups } : {})}
@@ -1381,6 +1567,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(railFrom !== undefined ? { railFrom } : {})}
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}
           {...(railTop !== undefined ? { railTop } : {})}
+          {...(railScrollbar !== undefined ? { railScrollbar } : {})}
+          {...(blockRhythm !== undefined ? { blockRhythm } : {})}
           {...(stickyToolbar !== undefined ? { stickyToolbar } : {})}
           {...(defaultFiltersOpen !== undefined ? { defaultFiltersOpen } : {})}
           {...(filtersOpen !== undefined ? { filtersOpen } : {})}

package/src/default/SearchResultsPane.tsx

@@ -487,6 +487,25 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
   /** Widest the column of results may grow (default {@link RESULTS_MAX_WIDTH});
    * `null` lets the container decide. */
   readonly maxWidth?: number | null;
+  /**
+   * THE BOX THE RESULTS ARRIVE INTO — a block-size floor the pane holds while
+   * the first answer is in flight, and drops the moment the rows land.
+   *
+   * The pane cannot know how tall its own page will be (the row count is the
+   * host's `limit` and the card height is the host's card), so this is a
+   * number the host measures once for its own feed — `limit × card + gaps` —
+   * and it stops the fold below the results from rising into the space the
+   * feed is about to take.
+   *
+   * What it replaces is a stylesheet rule aimed at this pane with the only
+   * hold a consumer had on it: `#search-page > :last-child`, a selector that
+   * silently starts addressing something else the day this page grows a
+   * seventh child. The pane's root now also carries
+   * `data-testid="search-results-pane"`, so a host that wants its own rule
+   * has a handle that is part of this pair's surface instead of a count of
+   * siblings.
+   */
+  readonly reserve?: number | string;
   /**
    * How the loaded rows are arranged: as many card columns as fit
    * (`"grid"`, the default) or one wide row each (`"list"`). The view SWITCH
@@ -713,6 +732,7 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
   return (
     <SkinTheme
       surface="base"
+      data-testid="search-results-pane"
       {...(props.mode !== undefined ? { mode: props.mode } : {})}
       style={{
         width: "100%",
@@ -721,7 +741,16 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
     >
       <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
         {(bag) => (
-          <Flex vertical gap={spacing[4]}>
+          <Flex
+            vertical
+            gap={spacing[4]}
+            // The box the results arrive into — see `reserve`. Only until the
+            // FIRST answer lands: a floor under rows already on screen would
+            // hold a gap open under a short page for the rest of the session.
+            {...(props.reserve !== undefined && bag.state.status === "loading"
+              ? { style: { minBlockSize: props.reserve } }
+              : {})}
+          >
             {props.lead !== undefined && (
               <div data-testid="search-results-lead">{props.lead}</div>
             )}

package/src/default/SortSelect.tsx

@@ -15,7 +15,7 @@
  * That is the whole defect this file used to carry: the one sort a person
  * would most want on a phone was greyed out with its explanation in a hover.
  */
-import type { ReactElement } from "react";
+import type { CSSProperties, ReactElement } from "react";
 import { Flex, Select, Typography } from "antd";
 import { actionAvailable, actionBlocked, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
@@ -34,6 +34,61 @@ import { sortLabelKey } from "./sortLabels.js";
  */
 export const SORT_SELECT_MIN_WIDTH = 200;
 
+/**
+ * The select's own chrome around its label: antd's two inline paddings plus
+ * the caret and its margin. Added to the compact form's sizer (below), which
+ * measures a bare label.
+ */
+export const SORT_SELECT_CHROME = 40;
+
+/**
+ * ── THE COMPACT CONTROL'S BOX, HELD FROM THE FIRST FRAME ────────────────────
+ *
+ * The compact arm draws `value={active ?? null}`, and `active` is only known
+ * once the page in cache reports the sort the SERVER applied (see
+ * {@link useAppliedSort}) — for an address that names no `sort`, that is a
+ * whole round trip after the first paint. So the control rendered as a bare
+ * caret and then GREW by the width of its label: measured on a category leaf,
+ * the caret's own box moved from x=22 to x=137, 115px, the largest single
+ * term in that page's layout shift. `minWidth: 0` was written inline, so no
+ * consumer stylesheet could hold the box either.
+ *
+ * The floor is not {@link SORT_SELECT_MIN_WIDTH}: 200px is the desktop arm's
+ * number and would wrap a two-control toolbar onto two rows at 390px. It is
+ * the width of the longest label THIS control can be asked to show, at the
+ * font it will show it in — so it is measured by the browser rather than
+ * guessed in pixels, and it is right in every locale (a Russian sort label is
+ * half again as long as its English original).
+ *
+ * One grid cell, two children stacked in it: an `aria-hidden` sizer carrying
+ * the longest label, and the select itself. The cell is as wide as the sizer,
+ * the select fills it, and neither depends on `active`.
+ */
+const COMPACT_WRAP: CSSProperties = {
+  display: "inline-grid",
+  flex: "0 1 auto",
+};
+
+const COMPACT_SIZER: CSSProperties = {
+  gridArea: "1 / 1",
+  visibility: "hidden",
+  blockSize: 0,
+  overflow: "hidden",
+  whiteSpace: "nowrap",
+  pointerEvents: "none",
+  paddingInline: SORT_SELECT_CHROME,
+};
+
+const COMPACT_SELECT: CSSProperties = { gridArea: "1 / 1", minWidth: 0 };
+
+/** The longest of the labels the control can display, which is the one the
+ * sizer holds. Ties keep the first — they are the same width. */
+export function longestSortLabel(labels: readonly string[]): string {
+  return labels.reduce((longest, label) =>
+    label.length > longest.length ? label : longest
+  , "");
+}
+
 /** Why `sort=distance` is refused without a centre — the server's own code, so
  * the control and the 400 it would have earned say the same sentence. */
 const SORT_DISTANCE_BLOCKED = "error.400.search_sort_needs_center";
@@ -49,9 +104,11 @@ export interface SortSelectProps {
    *
    *  - the "Sort" caption goes (the select already shows a sort by name; the
    *    accessible name keeps the word);
-   *  - the {@link SORT_SELECT_MIN_WIDTH} floor goes, so the control shares one
+   *  - the {@link SORT_SELECT_MIN_WIDTH} floor goes — the control shares one
    *    row with whatever the surface puts beside it instead of pushing it to
-   *    the next line;
+   *    the next line — and is replaced by a floor the width of this control's
+   *    OWN longest label, so the box does not grow when the answer names the
+   *    sort (see `COMPACT_WRAP`);
    *  - 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.
@@ -110,14 +167,25 @@ export function SortSelect(props: SortSelectProps): ReactElement {
    * accessible description of the SELECT, the other is the label of the OPTION
    * that is refused, and they are read in different moments.
    */
+  /**
+   * The names this control can DISPLAY, which is what the compact form's
+   * sizer is measured on. The blocked row's appended reason is deliberately
+   * not among them: it reaches the CLOSED control only for a sort the address
+   * itself names, and a sort in the address is known from the first frame —
+   * so it can widen the box but can never move it.
+   */
+  const plainLabels = values.map((value) => {
+    const key = sortLabelKey(value);
+    return key !== undefined ? t(key) : value;
+  });
+
   const optionsFor = (): {
     readonly value: string;
     readonly label: string;
     readonly disabled: boolean;
   }[] =>
-    values.map((value) => {
-      const key = sortLabelKey(value);
-      const label = key !== undefined ? t(key) : value;
+    values.map((value, index) => {
+      const label = plainLabels[index] ?? value;
       const blocked = value === "distance" && !hasCentre;
       return {
         value,
@@ -128,20 +196,23 @@ export function SortSelect(props: SortSelectProps): ReactElement {
 
   if (props.compact === true) {
     return (
-      <Select<string>
-        data-testid="search-sort"
-        data-stapel-gated={hasCentre ? "available" : "blocked"}
-        aria-label={t(SEARCH_I18N_KEYS.sortLabel)}
-        // `minWidth: 0` and not the floor: a control that refuses to be
-        // narrower than 200px is a control that wraps a two-item toolbar onto
-        // two rows at 390px.
-        style={{ minWidth: 0, flex: "0 1 auto" }}
-        value={active ?? null}
-        onChange={(next) => {
-          setSort(next);
-        }}
-        options={optionsFor()}
-      />
+      <div style={COMPACT_WRAP} data-testid="search-sort-compact">
+        {/* The box, not a caption — see `COMPACT_WRAP`. */}
+        <span aria-hidden="true" data-testid="search-sort-sizer" style={COMPACT_SIZER}>
+          {longestSortLabel(plainLabels)}
+        </span>
+        <Select<string>
+          data-testid="search-sort"
+          data-stapel-gated={hasCentre ? "available" : "blocked"}
+          aria-label={t(SEARCH_I18N_KEYS.sortLabel)}
+          style={COMPACT_SELECT}
+          value={active ?? null}
+          onChange={(next) => {
+            setSort(next);
+          }}
+          options={optionsFor()}
+        />
+      </div>
     );
   }
 

package/src/default/index.ts

@@ -42,7 +42,13 @@
 // ── surfaces ────────────────────────────────────────────────────────────────
 export {
   SearchPage,
+  BLOCK_GAP_COMPACT_VAR,
+  BLOCK_GAP_VAR,
+  BLOCK_RHYTHM_CLASS,
+  BLOCK_RHYTHM_STYLE_HREF,
+  blockRhythmCss,
   RAIL_CLASS,
+  RAIL_SCROLLBAR_CLASS,
   RAIL_STYLE_HREF,
   railScrollbarCss,
   railStyle,
@@ -53,7 +59,9 @@ export type {
   SearchFiltersHeader,
   SearchFiltersHeaderSlotProps,
   SearchFiltersOpenReason,
+  SearchBlockRhythm,
   SearchRailFrom,
+  SearchRailScrollbar,
 } from "./SearchPage.js";
 
 export {
@@ -93,7 +101,6 @@ export {
   CHIP_BAND_ORDER,
   CHIP_ROW_CAP,
   CHIP_ROW_CLASS,
-  CHIP_ROW_MIN_HEIGHT,
   CHIP_ROW_STYLE_HREF,
   appliedChipTestId,
   appliedRowMinHeight,
@@ -101,6 +108,7 @@ export {
   capChipRow,
   categoryLeaf,
   chipRowCss,
+  chipRowMinHeight,
   orderChipFilters,
   rangeChipText,
   rangeLabelSource,
@@ -179,7 +187,12 @@ export type { RankingDisclosurePaneProps } from "./RankingDisclosurePane.js";
 // ── controls, exported so a host can compose its own layout ─────────────────
 export { SearchBox } from "./SearchBox.js";
 export type { SearchBoxProps } from "./SearchBox.js";
-export { SortSelect, SORT_SELECT_MIN_WIDTH } from "./SortSelect.js";
+export {
+  SortSelect,
+  SORT_SELECT_CHROME,
+  SORT_SELECT_MIN_WIDTH,
+  longestSortLabel,
+} from "./SortSelect.js";
 export type { SortSelectProps } from "./SortSelect.js";
 export { ViewSwitch, SEARCH_BUILTIN_VIEWS, resolveView } from "./ViewSwitch.js";
 export type { ViewSwitchProps, SearchView, SearchResultsLayout } from "./ViewSwitch.js";