@stapel/search-react 0.41.2 → 0.42.1

package/src/default/SearchPage.tsx

@@ -61,12 +61,12 @@
  * nothing in it, and a layout that reflowed underneath a person mid-load would
  * be worse than the hole.
  */
-import { useState, useSyncExternalStore } from "react";
+import { useRef, useState, useSyncExternalStore } from "react";
 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 { breakpoints, cssVar, spacing } from "@stapel/tokens";
+import { breakpoints, 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";
@@ -77,6 +77,12 @@ import type { ParseSearchStateOptions } from "../state/urlState.js";
 import type { SearchGeo } from "../api/types.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { useRailFits } from "./railFit.js";
+import {
+  RAIL_SCROLLBAR_CLASS,
+  RAIL_STYLE_HREF,
+  railScrollbarCss,
+} from "./scrollbar.js";
 import { FacetPanelPane } from "./FacetPanelPane.js";
 import type {
   CategoryFilterSlotProps,
@@ -266,87 +272,27 @@ export const FILTERS_RAIL_WIDTH = 280;
 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.
+ * The skin's scrollbar, which is no longer only the RAIL's — the dictionary
+ * facet inside the panel is a scroll port too, and it kept the platform's bar
+ * painted over its count column. The rule set, the class, the `href` and the
+ * track's width now live in `./scrollbar.ts` so both ports mount one hoisted
+ * sheet; they are re-exported here unchanged because they are this package's
+ * published surface.
  */
-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";
+export {
+  RAIL_SCROLLBAR_CLASS,
+  RAIL_SCROLLBAR_WIDTH,
+  RAIL_STYLE_HREF,
+  railScrollbarCss,
+} from "./scrollbar.js";
 
 /** Whose scrollbar the rail's own scroll port draws — see
  * {@link SearchPageProps.railScrollbar}. */
 export type SearchRailScrollbar = "styled" | "system";
 
-/**
- * The scrollbar's track width, in CSS pixels.
- *
- * 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.
- *
- * 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 bar = `.${RAIL_SCROLLBAR_CLASS}`;
-  const size = `${String(RAIL_SCROLLBAR_WIDTH)}px`;
-  const thumb = cssVar("border");
-  const awake = `${bar}:hover,${bar}:focus-within`;
-  return [
-    // ── 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")}}`,
-    `${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");
-}
+/** WHAT SCROLLS when the filters are longer than the window — see
+ * {@link SearchPageProps.railScroll}. */
+export type SearchRailScroll = "internal" | "page";
 
 const RAIL: CSSProperties = {
   flex: `0 0 ${String(FILTERS_RAIL_WIDTH)}px`,
@@ -373,19 +319,59 @@ const RAIL: CSSProperties = {
   paddingBlockEnd: spacing[2],
 };
 
+/**
+ * The rail that is NOT a scroll port — `railScroll="page"`.
+ *
+ * The column, and nothing that makes it a container: no `overflow-y`, no
+ * height cap, no scroll gutter, no `overscroll-behavior`. What decides
+ * `position` is not written here but MEASURED — see {@link railStyle} and
+ * `useRailFits`.
+ */
+const RAIL_IN_PAGE: CSSProperties = {
+  flex: `0 0 ${String(FILTERS_RAIL_WIDTH)}px`,
+  minWidth: FILTERS_RAIL_WIDTH,
+  maxWidth: FILTERS_RAIL_WIDTH,
+  // Load-bearing in both arms: a flex child stretches to the row's height by
+  // default, and a stretched box has nothing to stick to.
+  alignSelf: "flex-start",
+  paddingBlockEnd: spacing[2],
+};
+
 /**
  * The rail with a host's own offset under it.
  *
- * `top` and the height cap move TOGETHER, and that is the whole reason this is
- * a function rather than one property: a rail pushed 64px down the window whose
- * cap is still `100dvh` ends 64px past the foot of the screen, so its last
- * control is unreachable — the internal scroll has scrolled past the window.
+ * Under the default `"internal"` arm, `top` and the height cap move TOGETHER,
+ * and that is the whole reason this is a function rather than one property: a
+ * rail pushed 64px down the window whose cap is still `100dvh` ends 64px past
+ * the foot of the screen, so its last control is unreachable — the internal
+ * scroll has scrolled past the window.
+ *
+ * Under `"page"` there is no cap and no port. The rail is sticky WHILE IT
+ * FITS (`fits`, measured by `useRailFits`) and static when it does not, since
+ * a stuck box taller than the window is cut off at the foot of the screen with
+ * no scroll of its own to reveal the rest. The offset is written twice on
+ * purpose: as `top`, which is what sticky uses, and as `scroll-margin-top`,
+ * which is the one property that MEANS "this much of the top of the scrollport
+ * is covered" and which the engine resolves to pixels for the fit test to read
+ * back.
  *
  * A number is pixels; a string is taken as written, so
  * `railTop="var(--stapel-header-height)"` reads the height `<PublicShell>`
  * publishes instead of restating it.
  */
-export function railStyle(top: number | string | undefined): CSSProperties {
+export function railStyle(
+  top: number | string | undefined,
+  scroll: SearchRailScroll = "internal",
+  fits = false
+): CSSProperties {
+  if (scroll === "page") {
+    const offset = top ?? 0;
+    return {
+      ...RAIL_IN_PAGE,
+      scrollMarginTop: offset,
+      ...(fits ? { position: "sticky", top: offset } : { position: "static" }),
+    };
+  }
   if (top === undefined) return RAIL;
   const offset = typeof top === "number" ? `${String(top)}px` : top;
   return { ...RAIL, top, maxHeight: `calc(100dvh - ${offset})` };
@@ -787,8 +773,40 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * 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.
+   *
+   * Read under `railScroll="page"` by nothing: a rail that is not a scroll
+   * port has no bar to dress, so neither the class nor the rule set is
+   * mounted there.
    */
   readonly railScrollbar?: SearchRailScrollbar;
+  /**
+   * WHAT SCROLLS when the filters are longer than the window.
+   * Default `"internal"` — no host changes behaviour by upgrading.
+   *
+   *  - `"internal"` — the rail is its own scroll container: it stays put at
+   *    {@link railTop} and the filters scroll INSIDE it, capped at the height
+   *    of the window. A person who has scrolled the filters and ticked one
+   *    does not find the page has moved under them;
+   *  - `"page"` — the rail is a column of the page and the PAGE is the only
+   *    thing that scrolls. No `overflow-y`, no height cap, no gutter, no
+   *    `overscroll-behavior`, and no scrollbar of its own to dress.
+   *
+   * `"page"` is not "sticky off". A rail SHORTER than the room under the
+   * host's chrome still pins at {@link railTop}, exactly as it does in the
+   * other arm — it is only the rail TALLER than the window that goes static,
+   * because a stuck box that tall is cut off at the foot of the screen and the
+   * page scroll, which is now the only scroll, cannot reach its last controls.
+   * Which of the two a leaf gets is measured (the rail's own height against
+   * `window.innerHeight` minus the offset), not guessed from a breakpoint: the
+   * same catalogue draws four facet groups on one section and twenty on the
+   * next.
+   *
+   * For the surface whose owner reads a second scrollbar standing beside the
+   * results as a second page — a storefront's whole filter column in one
+   * gesture with the feed — and for any host whose own chrome already gives
+   * the window one scroll and wants no other.
+   */
+  readonly railScroll?: SearchRailScroll;
   /**
    * WHAT THE FILTER PANEL'S OWN BODY PAINTS. Default `"flat"`.
    *
@@ -1026,6 +1044,7 @@ interface SearchPageBodyProps {
   readonly filtersLayout?: SearchFiltersLayout;
   readonly railTop?: number | string;
   readonly railScrollbar?: SearchRailScrollbar;
+  readonly railScroll?: SearchRailScroll;
   readonly railSurface?: SearchRailSurface;
   readonly blockRhythm?: SearchBlockRhythm;
   readonly stickyToolbar?: SearchToolbarPin;
@@ -1082,6 +1101,22 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
    */
   const footerBar: FacetPanelPaneProps["footerBar"] =
     props.footerBar ?? (layout === "sheet" ? undefined : "static");
+  /*
+   * THE RAIL'S OWN GEOMETRY, under `railScroll` — one element, one ref, and a
+   * measurement that only runs in the arm that needs it.
+   *
+   * The ref is on the rail for the whole life of the page: the fit answer must
+   * not arrive by REMOUNTING the column. Ticking a facet re-renders the panel
+   * inside this box; if the box itself were replaced, the browser would put
+   * the new one at the top of its flow and a person three screens down the
+   * results would be thrown back up the page — which is the very thing this
+   * arm exists to prevent.
+   */
+  const railRef = useRef<HTMLDivElement | null>(null);
+  const railFits = useRailFits(railRef, props.railScroll === "page");
+  /* The skin's bar dresses a scroll port, and under `"page"` there is none. */
+  const railStyled =
+    props.railScroll !== "page" && props.railScrollbar !== "system";
   // Controlled or not, decided by the PRESENCE of `filtersOpen` and read once
   // per render — the state the page keeps is only ever the uncontrolled half,
   // and a controlled host's value is never copied into it (copying it is how
@@ -1519,18 +1554,25 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       ) : showFilters ? (
         <Flex align="flex-start" gap={spacing[5]} data-testid="search-page-columns">
           <div
-            className={
-              props.railScrollbar === "system"
-                ? RAIL_CLASS
-                : `${RAIL_CLASS} ${RAIL_SCROLLBAR_CLASS}`
-            }
-            style={railStyle(props.railTop)}
+            ref={railRef}
+            className={railStyled ? `${RAIL_CLASS} ${RAIL_SCROLLBAR_CLASS}` : RAIL_CLASS}
+            style={railStyle(props.railTop, props.railScroll, railFits)}
+            {...(props.railScroll === "page"
+              ? {
+                  /* What the column IS doing, on the element that is doing it:
+                     a stand reads the arm and the measured answer instead of
+                     inferring both from a computed style. */
+                  "data-rail-scroll": "page",
+                  "data-rail-sticky": String(railFits),
+                }
+              : {})}
           >
             {/* The rail's scrollbar, in the gutter and in the token palette —
                 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" && (
+                at all under `"system"` — nor under `railScroll="page"`, where
+                there is no scroll port to dress: a sheet whose only selector is
+                a class nothing carries is dead weight in the document. */}
+            {railStyled && (
               <style href={RAIL_STYLE_HREF} precedence="default">
                 {railScrollbarCss()}
               </style>
@@ -1585,6 +1627,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     filtersLayout,
     railTop,
     railScrollbar,
+    railScroll,
     railSurface,
     blockRhythm,
     stickyToolbar,
@@ -1653,6 +1696,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}
           {...(railTop !== undefined ? { railTop } : {})}
           {...(railScrollbar !== undefined ? { railScrollbar } : {})}
+          {...(railScroll !== undefined ? { railScroll } : {})}
           {...(railSurface !== undefined ? { railSurface } : {})}
           {...(blockRhythm !== undefined ? { blockRhythm } : {})}
           {...(stickyToolbar !== undefined ? { stickyToolbar } : {})}

package/src/default/focusRing.ts

@@ -0,0 +1,100 @@
+/**
+ * A focus ring the KEYBOARD gets and the mouse does not.
+ *
+ * On a live storefront, clicking the "collapse" control under a facet group
+ * left a red outline standing around it until something else took focus. The
+ * ring itself is right — it is the design system's `:focus-visible` outline,
+ * and a keyboard must have it — but it was being drawn for a POINTER, which is
+ * the one modality that already knows where it clicked.
+ *
+ * ── Why `:focus-visible` alone is not the fix ─────────────────────────────
+ *
+ * The usual answer, "draw the ring on `:focus-visible` and not on `:focus`",
+ * was already true here: antd draws its button ring from
+ * `&:not(:disabled):focus-visible` and nothing in this pair or the storefront's
+ * sheet draws one on bare `:focus`. `:focus-visible` is a HEURISTIC, though,
+ * not a statement about the last input device: the engine may match it for a
+ * click when focus lands on an element whose surroundings have just changed
+ * under it — which is exactly what a disclosure toggle does to its own list.
+ * Suppressing the ring on `:focus:not(:focus-visible)` therefore fixes nothing
+ * on the very control that showed the defect.
+ *
+ * ── What this states instead ──────────────────────────────────────────────
+ *
+ * The modality, as a fact the control records for itself: a pointer press
+ * stamps `data-pointer-focus` on the element, and the first key it sees — or
+ * losing focus — clears it. The sheet then turns the ring OFF while that stamp
+ * is on, and leaves every other case to the design system. Tab to the control
+ * and the ring is there; click it and it is not; click it and then Tab back to
+ * it and it is there again, because the stamp died with the blur.
+ *
+ * The attribute is written straight to the node rather than held in state, on
+ * purpose: it is presentation the frame does not depend on, one control at a
+ * time, and a `useState` per facet button would re-render a rail of forty
+ * groups to paint an outline. React does not own this attribute, so nothing
+ * it renders fights over it.
+ *
+ * The class is doubled in the selector (`.c.c[…]`) for exactly one reason:
+ * specificity. antd's own ring is `.ant-btn:not(:disabled):focus-visible`
+ * (0,3,0); a single class plus the attribute plus the pseudo-class ties it, and
+ * a tie is settled by whichever stylesheet the engine saw last — which for a
+ * runtime CSS-in-JS design system is not a thing this pair gets to decide.
+ */
+import type { CSSProperties } from "react";
+
+/** The class the pointer-focus rule is hung on. */
+export const POINTER_FOCUS_CLASS = "stapel-search-pointer-focus";
+
+/** The attribute a pointer press stamps, and a key or a blur clears. */
+export const POINTER_FOCUS_ATTR = "data-pointer-focus";
+
+/** The `href` the hoisted focus sheet is deduplicated by (React 19). */
+export const POINTER_FOCUS_STYLE_HREF = "stapel-search-pointer-focus";
+
+/** See the module note. */
+export function pointerFocusCss(): string {
+  const c = `.${POINTER_FOCUS_CLASS}`;
+  return `${c}${c}[${POINTER_FOCUS_ATTR}]:focus-visible{outline:none;box-shadow:none}`;
+}
+
+/**
+ * The handlers a control spreads to opt into the rule above.
+ *
+ * Typed against the DOM rather than against React's synthetic event so the
+ * same object fits a native `<button>` and antd's `<Button>` — both forward
+ * these three props to the element, which is the only thing this needs.
+ */
+export interface PointerFocusProps {
+  readonly className: string;
+  readonly onPointerDown: (event: { currentTarget: Element }) => void;
+  readonly onKeyDown: (event: { currentTarget: Element }) => void;
+  readonly onBlur: (event: { currentTarget: Element }) => void;
+}
+
+/**
+ * Spread onto any control whose ring should be the keyboard's alone.
+ *
+ * A constant, not a hook: it closes over nothing, so one object serves every
+ * control in the tree and a facet group of forty rows allocates none.
+ */
+export const POINTER_FOCUS: PointerFocusProps = {
+  className: POINTER_FOCUS_CLASS,
+  onPointerDown: (event) => {
+    event.currentTarget.setAttribute(POINTER_FOCUS_ATTR, "");
+  },
+  onKeyDown: (event) => {
+    event.currentTarget.removeAttribute(POINTER_FOCUS_ATTR);
+  },
+  onBlur: (event) => {
+    event.currentTarget.removeAttribute(POINTER_FOCUS_ATTR);
+  },
+};
+
+/** {@link POINTER_FOCUS} with a className of the caller's own merged in. */
+export function pointerFocus(className: string): PointerFocusProps {
+  return { ...POINTER_FOCUS, className: `${className} ${POINTER_FOCUS_CLASS}` };
+}
+
+/** Nothing this module styles inline — exported so a host composing its own
+ * control can state the same intent without re-deriving the selector. */
+export const POINTER_FOCUS_NO_RING: CSSProperties = { outline: "none" };

package/src/default/index.ts

@@ -53,6 +53,22 @@ export {
   railScrollbarCss,
   railStyle,
 } from "./SearchPage.js";
+export { RAIL_OFFSET_PROPERTY, useRailFits } from "./railFit.js";
+export {
+  RAIL_SCROLLBAR_WIDTH,
+  SCROLL_GUTTER_INLINE_END,
+  SCROLL_LIST_INSET_BLOCK_START,
+} from "./scrollbar.js";
+export {
+  POINTER_FOCUS,
+  POINTER_FOCUS_ATTR,
+  POINTER_FOCUS_CLASS,
+  POINTER_FOCUS_NO_RING,
+  POINTER_FOCUS_STYLE_HREF,
+  pointerFocus,
+  pointerFocusCss,
+} from "./focusRing.js";
+export type { PointerFocusProps } from "./focusRing.js";
 export type {
   SearchPageProps,
   SearchFiltersLayout,
@@ -61,6 +77,7 @@ export type {
   SearchFiltersOpenReason,
   SearchBlockRhythm,
   SearchRailFrom,
+  SearchRailScroll,
   SearchRailScrollbar,
 } from "./SearchPage.js";
 
@@ -176,6 +193,7 @@ export {
   POPULAR_VALUES_COLUMNS,
   POPULAR_VALUES_LADDER,
   POPULAR_VALUES_LIMIT,
+  POPULAR_VALUES_MAX_COLUMNS,
   POPULAR_VALUES_STYLE_HREF,
   POPULAR_VALUE_COLUMN_WIDTH,
 } from "./PopularValues.js";

package/src/default/railFit.ts

@@ -0,0 +1,90 @@
+/**
+ * DOES THE FILTER RAIL FIT UNDER THE HOST'S HEADER?
+ *
+ * The question exists only for `railScroll="page"` — the arm where the rail is
+ * NOT a scroll container of its own and the page is the only thing that
+ * scrolls. There a rail taller than the window cannot be sticky: a stuck box
+ * is cut off at the foot of the screen and its last controls become
+ * unreachable, because the scroll that would reveal them is the page's and the
+ * page is not moving the rail. So the rail sticks while it fits and stands in
+ * flow while it does not, and "fits" is a measurement, not a breakpoint:
+ * the same catalogue draws four facet groups on one leaf and twenty on the
+ * next.
+ *
+ * Two numbers, and both are read from the browser rather than restated:
+ *
+ *  - the rail's own height — `ResizeObserver`, because the rail changes height
+ *    without the window changing at all (a facet group unfolds, an answer
+ *    lands with more values, the schema arrives and reorders the panel);
+ *  - the room under the host's chrome — `window.innerHeight` minus the offset
+ *    the rail already carries as `scroll-margin-top`. That property is the
+ *    same offset said in the one property that MEANS it (the header covers
+ *    that much of the top of the scrollport), and the engine resolves it to
+ *    pixels — a `var()`, a `calc()` or a `rem` included — so the fit test
+ *    needs no CSS parser of its own to read what a host wrote.
+ *
+ * The house rule from `useElementWidth` holds here too: **zero is not a
+ * measurement**. A detached or `display: none` rail reports 0 and would
+ * otherwise be declared to fit forever. And the honest answer before the first
+ * measurement is "no": a static rail scrolls with the page under every
+ * circumstance, so an unmeasured frame degrades to the arm that cannot hide a
+ * control.
+ */
+import { useEffect, useState } from "react";
+import type { RefObject } from "react";
+
+/** The CSS property the rail's top offset is carried in — see the note above.
+ * Exported so a test can assert the two halves read and write the same one. */
+export const RAIL_OFFSET_PROPERTY = "scrollMarginTop";
+
+/**
+ * Measure whether `ref`'s element is short enough to stand under the chrome
+ * its own `scroll-margin-top` names.
+ *
+ * `enabled` is the `railScroll === "page"` arm: under `"internal"` nothing is
+ * measured and nothing is listened to, so the default arm carries no observer
+ * and no listener at all.
+ */
+export function useRailFits(
+  ref: RefObject<HTMLElement | null>,
+  enabled: boolean
+): boolean {
+  const [fits, setFits] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) {
+      // Leaving the arm resets the answer: a rail that stops being measured
+      // must not keep the last measurement's `position: sticky`.
+      setFits(false);
+      return undefined;
+    }
+    const element = ref.current;
+    if (element === null) return undefined;
+
+    const measure = (): void => {
+      const height = element.getBoundingClientRect().height;
+      // Zero is not a measurement — see the note above.
+      if (height <= 0) return;
+      const offset = Number.parseFloat(
+        window.getComputedStyle(element)[RAIL_OFFSET_PROPERTY]
+      );
+      const room = window.innerHeight - (Number.isFinite(offset) ? offset : 0);
+      const next = height <= room;
+      setFits((previous) => (previous === next ? previous : next));
+    };
+
+    measure();
+    // The window's own height is not the element's: a rotation, a devtools
+    // pane or a resized window changes the room without changing the rail.
+    window.addEventListener("resize", measure);
+    const observer =
+      typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+    observer?.observe(element);
+    return () => {
+      window.removeEventListener("resize", measure);
+      observer?.disconnect();
+    };
+  }, [ref, enabled]);
+
+  return fits;
+}

package/src/default/scrollbar.ts

@@ -0,0 +1,119 @@
+/**
+ * The skin's scrollbar — one rule set, for every scroll port this pair owns.
+ *
+ * It started as the rail's own: `<SearchPage>` replaced the platform bar
+ * standing next to the filters with a 6px hairline in the token palette. But
+ * the rail is not the only box in the panel that scrolls — a dictionary facet
+ * (the make axis, 418 car makes) is a scroll port INSIDE the rail, and kept the
+ * platform's bar: on the live storefront the system thumb was painted over the
+ * count column, so «Chery 5» read as «Chery» with the 5 under a grey strip.
+ *
+ * A box that scrolls owes the reader two things, and both are here:
+ *
+ *  - `scrollbar-gutter: stable`, so the space the bar needs is subtracted from
+ *    the CONTENT box rather than overlaid on it, and the box's right edge does
+ *    not move when the thumb arrives;
+ *  - a thumb that is the skin's — a 6px track with no arrows and no track
+ *    fill, transparent at rest, appearing on `:hover` (a pointer scrolling
+ *    inside it) and `:focus-within` (a keyboard), and standing permanently
+ *    under `(pointer: coarse)`, where neither fires and an invisible bar is a
+ *    box with no sign it has a tail.
+ *
+ * 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 href precedence>` (React 19 dedupes by
+ * `href`), because a pseudo-element is unreachable from an inline style — so
+ * the rail and the dictionary list mount the SAME element, once, however many
+ * of each are on screen.
+ *
+ * The names still say "rail" and they stay that way: they are this package's
+ * published surface, and a hoisted sheet is identified by its `href`. Renaming
+ * them would break every host that reads the class to assert which bar is on
+ * screen, and would buy nothing but a tidier word.
+ */
+import type { CSSProperties } from "react";
+import { cssVar, spacing } from "@stapel/tokens";
+
+/**
+ * The class that carries the SKIN's scrollbar — present on the rail 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. Always present
+ * on a scroll port INSIDE the panel, which is not a surface a host chose.
+ */
+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";
+
+/**
+ * The scrollbar's track width, in CSS pixels.
+ *
+ * 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.
+ */
+export const RAIL_SCROLLBAR_WIDTH = 6;
+
+/** See the module note. */
+export function railScrollbarCss(): string {
+  const bar = `.${RAIL_SCROLLBAR_CLASS}`;
+  const size = `${String(RAIL_SCROLLBAR_WIDTH)}px`;
+  const thumb = cssVar("border");
+  const awake = `${bar}:hover,${bar}:focus-within`;
+  return [
+    // ── 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")}}`,
+    `${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");
+}
+
+/**
+ * What a scroll port inside the panel reserves at its trailing edge.
+ *
+ * `scrollbar-gutter: stable` is the rule and the sheet above states it; this
+ * is the same number as a value, for the ROW to keep its last column clear of.
+ * `scrollbar-gutter` subtracts the gutter from the scroll container's content
+ * box, which is enough on every engine that honours it — and is ignored
+ * outright by Safari, where an overlay thumb still lands on top of whatever
+ * sits at the trailing edge. A count is the one thing in a facet row that
+ * lives there, so it carries the gutter as padding of its own: correct twice
+ * over on Chromium and Firefox, and the only thing standing between the number
+ * and the thumb on WebKit.
+ */
+export const SCROLL_GUTTER_INLINE_END: CSSProperties = {
+  paddingInlineEnd: RAIL_SCROLLBAR_WIDTH,
+};
+
+/**
+ * The top of a list that sits directly under a control.
+ *
+ * The dictionary list's first row was drawn flush against the box that filters
+ * it — at a glance the row read as clipped BY the input rather than as the
+ * first value under it. One step of the scale is the whole fix; it is stated
+ * here rather than inline so the rail's two scroll ports open the same way.
+ */
+export const SCROLL_LIST_INSET_BLOCK_START: number = spacing[1];