@stapel/search-react 0.42.0 → 0.42.2

package/dist/default/scrollbar.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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";
+/**
+ * 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 declare const RAIL_SCROLLBAR_CLASS = "stapel-search-rail-scrollbar";
+/** The `href` the hoisted rail sheet is deduplicated by. */
+export declare 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 declare const RAIL_SCROLLBAR_WIDTH = 6;
+/** See the module note. */
+export declare function railScrollbarCss(): string;
+/**
+ * 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 declare const SCROLL_GUTTER_INLINE_END: CSSProperties;
+/**
+ * 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 declare const SCROLL_LIST_INSET_BLOCK_START: number;
+//# sourceMappingURL=scrollbar.d.ts.map

package/dist/default/scrollbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollbar.d.ts","sourceRoot":"","sources":["../../src/default/scrollbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAG3C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,iCAAiC,CAAC;AAEnE,4DAA4D;AAC5D,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,2BAA2B;AAC3B,wBAAgB,gBAAgB,IAAI,MAAM,CAsBzC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAEtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAmB,CAAC"}

package/dist/default/scrollbar.js

@@ -0,0 +1,69 @@
+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() {
+    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 = {
+    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 = spacing[1];
+//# sourceMappingURL=scrollbar.js.map

package/dist/default/scrollbar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollbar.js","sourceRoot":"","sources":["../../src/default/scrollbar.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,8BAA8B,CAAC;AAEnE,4DAA4D;AAC5D,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,2BAA2B;AAC3B,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,IAAI,CAAC;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,GAAG,GAAG,UAAU,GAAG,eAAe,CAAC;IACjD,OAAO;QACL,0EAA0E;QAC1E,GAAG,GAAG,gDAAgD;YACpD,0CAA0C;QAC5C,GAAG,KAAK,oBAAoB,KAAK,eAAe;QAChD,0EAA0E;QAC1E,GAAG,GAAG,mCAAmC,IAAI,eAAe,IAAI,GAAG;QACnE,GAAG,GAAG,mDAAmD;QACzD,GAAG,GAAG,mDAAmD;YACvD,iBAAiB,MAAM,CAAC,aAAa,CAAC,GAAG;QAC3C,GAAG,GAAG,kCAAkC;YACtC,GAAG,GAAG,qDAAqD,KAAK,GAAG;QACrE,GAAG,GAAG,8CAA8C,MAAM,CAAC,aAAa,CAAC,GAAG;QAC5E,0EAA0E;QAC1E,2BAA2B,GAAG,oBAAoB,KAAK,eAAe;YACpE,GAAG,GAAG,wCAAwC,KAAK,IAAI;KAC1D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAkB;IACrD,gBAAgB,EAAE,oBAAoB;CACvC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAW,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/search-react 0.42.0
+# @stapel/search-react 0.42.2
 
 Headless React flow pair for stapel-search (contract >=0.16 <0.17) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/search-react",
-  "version": "0.42.0",
+  "version": "0.42.2",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.16 <0.17"

package/nav-manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.42.0",
+  "version": "0.42.2",
   "description": "Headless React pair for stapel-search: a typed query client, TanStack Query hooks, and a URL-first state codec that makes a search shareable by construction (filters, ranges, geo, sort and the keyset cursor all live in the query string). Drill-down facets rendered with their remaining counts and with the server's own honesty flags — approximate, skipped, degraded — never swallowed; keyset pagination with the window refusal named; DSA Art. 26 `promoted` marking carried into every card slot and the P2B Art. 5 ranking disclosure exposed as data. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin, and /router binds the codec to react-router's useSearchParams.",
   "license": "MIT",
   "repository": {
@@ -57,9 +57,9 @@
       "limit": "14.5 KB"
     },
     {
-      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes, then 29.25 → 30.5 KB for the panel that draws all of it: groups and ranges as one ordered sequence with one «Apply» for the panel rather than one per row, the empty-group heading rule, `categoryFilter={false}` and the `resultsLead` slot for a page reached by walking the catalogue, `PopularValues columns=\\\"responsive\\\"` on a container query, `SortSelect` annotating a blocked option at every width, a loading arm that covers the whole pane (0.34 CLS on a live host), and the chip row reserving its own box (a further 0.045). Measured with dependencies held constant, this package's src at the commit before that work and then at it: 29.05 -> 30.16 KB — 1.11 KB, and every part of it is a shift or a mislabelled control a host was living with, then 30.5 -> 31 KB for `<SearchResultsPane columns>` and its pass-through on `<SearchPage resultsColumns>`: a fixed track count or a per-breakpoint map, emitted as a hoisted container-query sheet (the results block is the window minus a 280px rail, so a media query would answer about a width the cards never have). Measured with dependencies held constant, this package's src before and after: 30.40 -> 30.65 KB — 250 B, and what it replaces is a host's `!important` rule against a grid declaration it could not read back, then 31 -> 31.25 KB for the segmented partition being antd's `Segmented` rather than a row of buttons wearing a border: the walker read `data-variant=\"segmented\"` with `role=\"radiogroup\"` and found `.ant-segmented` zero times and `input[type=radio]` zero times (D304), so the cells are the design system's now — real radios under one name, the browser's own arrow keys and Tab stop. Measured with dependencies held constant, this package's src before and after: 30.95 -> 31.05 KB — 100 B, against ~30 lines of hand-rolled joined-row geometry deleted, then 31.25 -> 31.5 KB for the two PINNING seams: `<SearchPage railTop>` (the rail's sticky offset and its height cap moved together, so a rail under a 64px header still ends at the foot of the window) and `<SearchResultsPane stickyToolbar>` with the toolbar's own element in both header shapes. Measured with dependencies held constant, this package's src before and after: 31.05 -> 31.2 KB — 150 B, and what it replaces in one deployment is an `!important` over the pair's own inline geometry, a `:has()`, a `display: contents` and this pair's rail breakpoint restated in the host's media query, then 31.5 -> 31.75 KB for the rail saying when its answer is IN FLIGHT: `FacetPanelBag.refreshing` off `loadStateFromQuery(…, { keepPrevious })`, `data-facets-refreshing` on the rail, and each facet group standing on its own last measured height (a `min-block-size` floor held in a ref) until the new answer lands. Measured with dependencies held constant, this package's src before and after: 31.43 -> 31.51 KB — 80 B, against 0.0586 CLS on a partition press (p43), where the groups survive and RESIZE, then 31.75 -> 32 KB for the FIRST MOUNT, which had none of that: `refreshing` is never true on a cold load, so nothing above reached the one pass a plain load is made of. Three parts. `<SearchPage categoryFeaturesPending>` / `<FacetPanelPane categoryFeaturesPending>` is the third state `categoryFeatures` never had — undefined means both \"no schema\" and \"not yet\", and on a category leaf the schema is a SECOND read, so the panel drew the rail from the answer alone and then drew it again when the schema landed: on the live cars leaf make and model went from three-row checkbox lists to one-row dictionary fields, condition and colour from checkboxes to pills, and `orderFacetGroupsBySchema` reordered all of them (p41, 0.0586 CLS on a plain load of `/c/transport-avtomobili`, make -152px and model -76px). Told the schema is coming, the panel keeps the box it already reserves and draws the rail ONCE. Second, every group now stands on a DECLARED box from the frame it mounts in (`facetGroupReservedHeight` — heading, rows and fold per shape), with its measured height preferred only while an answer is in flight. Third, `<SearchPage filtersHeaderReserve>` puts the host's own band above the rail in flow from the first frame, for the partition row that is two chained catalogue reads behind the answer. Measured with dependencies held constant, this package's src before and after: 30.77 -> 31.14 KB — 366 B, then 32 -> 32.25 KB for the filter sheet's open state becoming the HOST's: `<SearchPage filtersOpen>` / `onFiltersOpenChange(open, reason)` as React's usual controlled pair, and `filtersHeader` accepting a function handed `{ closeFilters, open }`. What it costs is the four call sites naming WHY the sheet moved (`open`, `apply`, `dismiss`, `consumer`) and the slot's function arm; what it buys is a header whose own control NAVIGATES being able to take the sheet down on the same press — the page published only `defaultFiltersOpen`, so a partition chip inside the sheet left the drawer standing over the page it had just opened. Measured with dependencies held constant, this package's src before and after: 31.14 -> 31.26 KB — 120 B, then 32.25 -> 32.5 KB for the two levers a storefront could not reach: `<SearchPage footerBar>` (the rail's footer bar writes its own `display` inline, so a consumer stylesheet could only suppress it with an `!important` its own gate forbids, and this page hard-coded the column's value) and `PartitionChild.count`, which the chip draws itself in the muted weight the facet rows use instead of a host welding the number onto the name. Measured with dependencies held constant, this package's src before and after: 32.01 -> 32.10 KB — 90 B, against a string-joining hack and an unreachable bar, then 32.5 -> 32.75 KB for THE THREE BOXES A STOREFRONT WAS HOLDING FOR THIS PAIR. The phone chip row's reserve is `chipRowMinHeight(token.controlHeight)` instead of a `44 + …` constant: the touch floor raises the chips to 44 only BELOW the tablet breakpoint, so from 768px up the reserve stood 12px taller than the 40px row and the results pane ROSE when the row landed (0.0725 CLS on a category leaf at 768, against 0.00016 at 390). `<SortSelect compact>` reserves the width of the longest label it can display, measured by the browser through an `aria-hidden` sizer stacked with the select in one grid cell, instead of `minWidth: 0` inline and a control that GREW 115px when the answer named the sort. And `<SearchResultsPane>` names its own root (`data-testid=\"search-results-pane\"`) and takes `reserve` — `<SearchPage resultsReserve>` — for the box the feed arrives into, which a host was holding with `#search-page > :last-child`. Measured with dependencies held constant, this package's src before and after: 32.10 -> 32.25 KB — 150 B, against a hand-guessed height, a sibling-count selector and two stylesheet rules a consumer can now delete. 32.75 KB HOLDS for the rail's own scrollbar and the block rhythm (owner's walk of the storefront, dark theme): measured 32539 B against the 32.75 KB line, 290 B over the 32249 B this note last recorded, and 211 B of room left. The rail stays its own scroll container — filters that stay put while the results move under them is the whole point of it — and `railScrollbar` names whose BAR draws in the gutter: `\"styled\"` (the new default) is a hoisted rule set in both vendor forms, a 6px track with no arrows and no track fill and a thumb that is transparent at rest and arrives from the tokens on hover or focus-within, standing always under `(pointer: coarse)` where neither fires; `\"system\"` hands the port back to the platform and mounts no sheet at all. The system bar was never a decision, which is why the default is the new arm. The rest is `blockRhythm`: one gap for every block on this page from `var(--stapel-block-gap)` / `var(--stapel-block-gap-compact)` with each block's outer margin reset, in place of the flat `spacing[4]` the root `<Flex>` wrote inline. A budget is not raised for a change that fits under the line it already has. 32.75 -> 33.25 KB for THE POINTER THAT WAS A PARTITION CHIP (owner's read of the stand at 0.38.0). Measured with dependencies held constant, this package's src before this change and then at it: 32539 -> 32779 B — 240 B, 29 of them over the old line, and a ceiling that fails on 29 B of a shipped defect fix is a gate proving nothing. `PartitionChild.linked`/`href` and `<PartitionChips linkedChildren>` split the row's items ONCE, above everything that reads them: the cells, the roving stop, the value lookup and the arrow keys see only the SECTIONS, so a pointer cannot be a radio, cannot carry a count and cannot be the chosen partition — the live row read `All | New 0 | Used 3 | Car rental 0`, where the last zero counted a category that is not a section of this template at all. The rest is the pointer's own chip: an outlined pill that is a real `<a href>` to the target, its inline arrow glyph (drawn here, like every other glyph in this skin — this package ships no icon set), and the row that carries them OUTSIDE the radiogroup, because a `role=\"radiogroup\"` containing a link announces a choice with an option nobody can choose. 33.25 KB leaves 471 B, then 33.25 -> 34 KB for THE TWO THINGS THE CLOSING-WAVE CENSUS FOUND ON THE FEED AND THE RAIL. Measured with dependencies held constant, this package's src before this change and then at it: 32779 -> 33584 B — 805 B, 334 of them over the old line. First, `<SearchPage toolbarSticky>` (default `true`): the results toolbar pins itself at `railTop` — the same edge the filter rail already clears, so there is no second number to keep in step — through a hoisted `@media (pointer: fine)` rule set, because the pin has to be gated on a pointer and a media query cannot be written in a `style` attribute. `stickyToolbar` shipped a release ago and no deployment turned it on, which is a feature nobody has; the reference pins its sort bar once a reader has scrolled into the results (REPORT §24, Surface 2) and this page now does too, on a desktop only — a pinned bar over a 390px viewport spends the fold on chrome. The row also states its own box from the first frame (`toolbarRowMinHeight(token.controlHeight)`, the discipline `chipRowMinHeight` is written under), so its height cannot change around the moment the rule engages. Second, the colour SWATCH: a facet whose axis is a colour (`isColorAxis` — the slug's head, the address key beside it, and `axis_role` the day the canon grows a colour one) draws a filled dot beside every value whose code it can resolve to an actual colour (`swatchColor` — a design-system colour role first, then CSS's own keyword vocabulary, then a hex code a catalogue spelled out itself), and NOTHING beside the rest. Most of the weight is that keyword list, and it is the whole point of the feature: it is the vocabulary in which \"this code names a colour\" is a fact rather than a guess, and without it the only alternatives are a hue table invented for one catalogue's transliterations or a grey placeholder saying every value is the same colour. 34 KB leaves 416 B. 34 KB HOLDS for the owner's tidiness probe on the stand (dark theme): measured 33661 B against the 34 KB line, 77 B over the 33584 B this note last recorded, and 339 B of room left. Three fills, all of them this pair drawing something the page had already decided. `<SearchPage railSurface>` / `<FacetPanelPane railSurface>` (default `\"flat\"`, `\"panel\"` restores the old arm): the filter panel's body painted the raised container ground and read as a 270 x 1539 filled slab with no radius and no border, standing on the page ground for the whole height of the feed — flat draws the controls and only the text colour a bare surface drops (`var(--stapel-text)`), the same answer `categories-react` gave for its grid, strip and breadcrumbs. The rail's footer bar stopped choosing a colour: it painted antd's `colorBgContainer` in both arms, and now paints the panel's OWN token and only in the pinned arm, which is the one with a scroll port under it — the static arm paints nothing and keeps its hairline. And `resultsHeader`'s wrapper is `display: contents`: it was mounted on the PROP rather than on what the prop rendered, so a host whose header said nothing still put a 1392 x 0 element in the block-rhythm column, which is charged a gap on BOTH sides — 64px between two real blocks where 32 is declared, on every feed page, plus a `:empty` stand-in rule in the consumer's stylesheet that can now be deleted. A budget is not raised for a change that fits under the line it already has, then 34 -> 34.5 KB for THE RAIL THAT SCROLLS WITH THE PAGE (`railScroll`, a founder's ruling on a client storefront). Measured with dependencies held constant, this package's src before this change and then at it: 33661 -> 34193 B — 532 B, 193 of them over the old line. The rail has been its own scroll container since it became sticky and stays one by default; `railScroll=\"page\"` is the other answer, for a surface whose owner reads a second scrollbar standing beside the results as a second page: no `overflow-y`, no height cap, no gutter, no `overscroll-behavior`, and no bar to dress a port that is not there. The weight is the half that is NOT a deletion, because `\"page\"` is not \"sticky off\": a rail SHORTER than the room under the host's chrome still pins at `railTop`, and only a rail taller than the window goes static — a stuck box that tall is cut off at the foot of the screen, and the page scroll, now the only scroll on the surface, cannot reach its last controls. Which of the two a leaf gets is MEASURED and not guessed from a breakpoint (`useRailFits`: the rail's own height against `window.innerHeight` minus the offset it carries as `scroll-margin-top`, an observer for the element and a listener for the window, and zero refused as a measurement), because the same catalogue draws four facet groups on one section and twenty on the next. 34.5 KB leaves 307 B",
+      "name": "default — the antd skin (query box + a typeahead that offers CATEGORY destinations with their live counts, filters incl. ranges/geo/category slots + the phone chip row with its leading category chip and the location summary row + the rail's evidence-ranked disclosure groups, panel search and sticky count/clear footer, results incl. the view switch, the card photo GALLERY as a SkinCarousel strip, the empty state's derived exits, ranking, the dictionary control for a vocabulary facet, the popular-values block, the partition row in both its chip and segmented variants, the select-style dictionary FIELD the desktop rail opens, the from/to pickers a bounded integer axis draws and the rail's own scrollbar sheet) must stay out of the main bundle. Raised 24.5 → 25.5 KB for those four controls, then 25.5 → 26.25 KB for the chip row's APPLIED mode — one chip per applied value and per numeric bound, each removing that one constraint beside a rail that is already on screen (a storefront was carrying its own copy of it), then 26.25 → 27 KB for the \"search in other categories\" LINE — which is a net deletion on the page that mounts it, replacing a full-width block of one row per section that arrived after the results and pushed them, then 27 → 27.75 KB for the two frames the page now tells apart: the dictionary FIELD reaching `<SearchPage>` at all (per-layout default, field in the rail and inline in the sheet) and the footer bar being static in a column and sticky in a sheet, where it used to be pinned over the last two groups everywhere, then 27.75 → 28.5 KB for `categoryHref` on the other-categories line — a real `<a href>` per row with a modifier-click left to the browser, instead of a `<button>` with no address a person could open in a new tab, then 28.5 → 29.25 KB for the phone's dictionary SHEET — a trigger row over the shared `SkinPickerSheet` with a recommended band, an alphabetical rest paged fifty at a time and a draft committed in one write, which is the control the composer's vocabulary picker already was while the buyer got a wall of checkboxes, then 29.25 → 30.5 KB for the panel that draws all of it: groups and ranges as one ordered sequence with one «Apply» for the panel rather than one per row, the empty-group heading rule, `categoryFilter={false}` and the `resultsLead` slot for a page reached by walking the catalogue, `PopularValues columns=\\\"responsive\\\"` on a container query, `SortSelect` annotating a blocked option at every width, a loading arm that covers the whole pane (0.34 CLS on a live host), and the chip row reserving its own box (a further 0.045). Measured with dependencies held constant, this package's src at the commit before that work and then at it: 29.05 -> 30.16 KB — 1.11 KB, and every part of it is a shift or a mislabelled control a host was living with, then 30.5 -> 31 KB for `<SearchResultsPane columns>` and its pass-through on `<SearchPage resultsColumns>`: a fixed track count or a per-breakpoint map, emitted as a hoisted container-query sheet (the results block is the window minus a 280px rail, so a media query would answer about a width the cards never have). Measured with dependencies held constant, this package's src before and after: 30.40 -> 30.65 KB — 250 B, and what it replaces is a host's `!important` rule against a grid declaration it could not read back, then 31 -> 31.25 KB for the segmented partition being antd's `Segmented` rather than a row of buttons wearing a border: the walker read `data-variant=\"segmented\"` with `role=\"radiogroup\"` and found `.ant-segmented` zero times and `input[type=radio]` zero times (D304), so the cells are the design system's now — real radios under one name, the browser's own arrow keys and Tab stop. Measured with dependencies held constant, this package's src before and after: 30.95 -> 31.05 KB — 100 B, against ~30 lines of hand-rolled joined-row geometry deleted, then 31.25 -> 31.5 KB for the two PINNING seams: `<SearchPage railTop>` (the rail's sticky offset and its height cap moved together, so a rail under a 64px header still ends at the foot of the window) and `<SearchResultsPane stickyToolbar>` with the toolbar's own element in both header shapes. Measured with dependencies held constant, this package's src before and after: 31.05 -> 31.2 KB — 150 B, and what it replaces in one deployment is an `!important` over the pair's own inline geometry, a `:has()`, a `display: contents` and this pair's rail breakpoint restated in the host's media query, then 31.5 -> 31.75 KB for the rail saying when its answer is IN FLIGHT: `FacetPanelBag.refreshing` off `loadStateFromQuery(…, { keepPrevious })`, `data-facets-refreshing` on the rail, and each facet group standing on its own last measured height (a `min-block-size` floor held in a ref) until the new answer lands. Measured with dependencies held constant, this package's src before and after: 31.43 -> 31.51 KB — 80 B, against 0.0586 CLS on a partition press (p43), where the groups survive and RESIZE, then 31.75 -> 32 KB for the FIRST MOUNT, which had none of that: `refreshing` is never true on a cold load, so nothing above reached the one pass a plain load is made of. Three parts. `<SearchPage categoryFeaturesPending>` / `<FacetPanelPane categoryFeaturesPending>` is the third state `categoryFeatures` never had — undefined means both \"no schema\" and \"not yet\", and on a category leaf the schema is a SECOND read, so the panel drew the rail from the answer alone and then drew it again when the schema landed: on the live cars leaf make and model went from three-row checkbox lists to one-row dictionary fields, condition and colour from checkboxes to pills, and `orderFacetGroupsBySchema` reordered all of them (p41, 0.0586 CLS on a plain load of `/c/transport-avtomobili`, make -152px and model -76px). Told the schema is coming, the panel keeps the box it already reserves and draws the rail ONCE. Second, every group now stands on a DECLARED box from the frame it mounts in (`facetGroupReservedHeight` — heading, rows and fold per shape), with its measured height preferred only while an answer is in flight. Third, `<SearchPage filtersHeaderReserve>` puts the host's own band above the rail in flow from the first frame, for the partition row that is two chained catalogue reads behind the answer. Measured with dependencies held constant, this package's src before and after: 30.77 -> 31.14 KB — 366 B, then 32 -> 32.25 KB for the filter sheet's open state becoming the HOST's: `<SearchPage filtersOpen>` / `onFiltersOpenChange(open, reason)` as React's usual controlled pair, and `filtersHeader` accepting a function handed `{ closeFilters, open }`. What it costs is the four call sites naming WHY the sheet moved (`open`, `apply`, `dismiss`, `consumer`) and the slot's function arm; what it buys is a header whose own control NAVIGATES being able to take the sheet down on the same press — the page published only `defaultFiltersOpen`, so a partition chip inside the sheet left the drawer standing over the page it had just opened. Measured with dependencies held constant, this package's src before and after: 31.14 -> 31.26 KB — 120 B, then 32.25 -> 32.5 KB for the two levers a storefront could not reach: `<SearchPage footerBar>` (the rail's footer bar writes its own `display` inline, so a consumer stylesheet could only suppress it with an `!important` its own gate forbids, and this page hard-coded the column's value) and `PartitionChild.count`, which the chip draws itself in the muted weight the facet rows use instead of a host welding the number onto the name. Measured with dependencies held constant, this package's src before and after: 32.01 -> 32.10 KB — 90 B, against a string-joining hack and an unreachable bar, then 32.5 -> 32.75 KB for THE THREE BOXES A STOREFRONT WAS HOLDING FOR THIS PAIR. The phone chip row's reserve is `chipRowMinHeight(token.controlHeight)` instead of a `44 + …` constant: the touch floor raises the chips to 44 only BELOW the tablet breakpoint, so from 768px up the reserve stood 12px taller than the 40px row and the results pane ROSE when the row landed (0.0725 CLS on a category leaf at 768, against 0.00016 at 390). `<SortSelect compact>` reserves the width of the longest label it can display, measured by the browser through an `aria-hidden` sizer stacked with the select in one grid cell, instead of `minWidth: 0` inline and a control that GREW 115px when the answer named the sort. And `<SearchResultsPane>` names its own root (`data-testid=\"search-results-pane\"`) and takes `reserve` — `<SearchPage resultsReserve>` — for the box the feed arrives into, which a host was holding with `#search-page > :last-child`. Measured with dependencies held constant, this package's src before and after: 32.10 -> 32.25 KB — 150 B, against a hand-guessed height, a sibling-count selector and two stylesheet rules a consumer can now delete. 32.75 KB HOLDS for the rail's own scrollbar and the block rhythm (owner's walk of the storefront, dark theme): measured 32539 B against the 32.75 KB line, 290 B over the 32249 B this note last recorded, and 211 B of room left. The rail stays its own scroll container — filters that stay put while the results move under them is the whole point of it — and `railScrollbar` names whose BAR draws in the gutter: `\"styled\"` (the new default) is a hoisted rule set in both vendor forms, a 6px track with no arrows and no track fill and a thumb that is transparent at rest and arrives from the tokens on hover or focus-within, standing always under `(pointer: coarse)` where neither fires; `\"system\"` hands the port back to the platform and mounts no sheet at all. The system bar was never a decision, which is why the default is the new arm. The rest is `blockRhythm`: one gap for every block on this page from `var(--stapel-block-gap)` / `var(--stapel-block-gap-compact)` with each block's outer margin reset, in place of the flat `spacing[4]` the root `<Flex>` wrote inline. A budget is not raised for a change that fits under the line it already has. 32.75 -> 33.25 KB for THE POINTER THAT WAS A PARTITION CHIP (owner's read of the stand at 0.38.0). Measured with dependencies held constant, this package's src before this change and then at it: 32539 -> 32779 B — 240 B, 29 of them over the old line, and a ceiling that fails on 29 B of a shipped defect fix is a gate proving nothing. `PartitionChild.linked`/`href` and `<PartitionChips linkedChildren>` split the row's items ONCE, above everything that reads them: the cells, the roving stop, the value lookup and the arrow keys see only the SECTIONS, so a pointer cannot be a radio, cannot carry a count and cannot be the chosen partition — the live row read `All | New 0 | Used 3 | Car rental 0`, where the last zero counted a category that is not a section of this template at all. The rest is the pointer's own chip: an outlined pill that is a real `<a href>` to the target, its inline arrow glyph (drawn here, like every other glyph in this skin — this package ships no icon set), and the row that carries them OUTSIDE the radiogroup, because a `role=\"radiogroup\"` containing a link announces a choice with an option nobody can choose. 33.25 KB leaves 471 B, then 33.25 -> 34 KB for THE TWO THINGS THE CLOSING-WAVE CENSUS FOUND ON THE FEED AND THE RAIL. Measured with dependencies held constant, this package's src before this change and then at it: 32779 -> 33584 B — 805 B, 334 of them over the old line. First, `<SearchPage toolbarSticky>` (default `true`): the results toolbar pins itself at `railTop` — the same edge the filter rail already clears, so there is no second number to keep in step — through a hoisted `@media (pointer: fine)` rule set, because the pin has to be gated on a pointer and a media query cannot be written in a `style` attribute. `stickyToolbar` shipped a release ago and no deployment turned it on, which is a feature nobody has; the reference pins its sort bar once a reader has scrolled into the results (REPORT §24, Surface 2) and this page now does too, on a desktop only — a pinned bar over a 390px viewport spends the fold on chrome. The row also states its own box from the first frame (`toolbarRowMinHeight(token.controlHeight)`, the discipline `chipRowMinHeight` is written under), so its height cannot change around the moment the rule engages. Second, the colour SWATCH: a facet whose axis is a colour (`isColorAxis` — the slug's head, the address key beside it, and `axis_role` the day the canon grows a colour one) draws a filled dot beside every value whose code it can resolve to an actual colour (`swatchColor` — a design-system colour role first, then CSS's own keyword vocabulary, then a hex code a catalogue spelled out itself), and NOTHING beside the rest. Most of the weight is that keyword list, and it is the whole point of the feature: it is the vocabulary in which \"this code names a colour\" is a fact rather than a guess, and without it the only alternatives are a hue table invented for one catalogue's transliterations or a grey placeholder saying every value is the same colour. 34 KB leaves 416 B. 34 KB HOLDS for the owner's tidiness probe on the stand (dark theme): measured 33661 B against the 34 KB line, 77 B over the 33584 B this note last recorded, and 339 B of room left. Three fills, all of them this pair drawing something the page had already decided. `<SearchPage railSurface>` / `<FacetPanelPane railSurface>` (default `\"flat\"`, `\"panel\"` restores the old arm): the filter panel's body painted the raised container ground and read as a 270 x 1539 filled slab with no radius and no border, standing on the page ground for the whole height of the feed — flat draws the controls and only the text colour a bare surface drops (`var(--stapel-text)`), the same answer `categories-react` gave for its grid, strip and breadcrumbs. The rail's footer bar stopped choosing a colour: it painted antd's `colorBgContainer` in both arms, and now paints the panel's OWN token and only in the pinned arm, which is the one with a scroll port under it — the static arm paints nothing and keeps its hairline. And `resultsHeader`'s wrapper is `display: contents`: it was mounted on the PROP rather than on what the prop rendered, so a host whose header said nothing still put a 1392 x 0 element in the block-rhythm column, which is charged a gap on BOTH sides — 64px between two real blocks where 32 is declared, on every feed page, plus a `:empty` stand-in rule in the consumer's stylesheet that can now be deleted. A budget is not raised for a change that fits under the line it already has, then 34 -> 34.5 KB for THE RAIL THAT SCROLLS WITH THE PAGE (`railScroll`, a founder's ruling on a client storefront). Measured with dependencies held constant, this package's src before this change and then at it: 33661 -> 34193 B — 532 B, 193 of them over the old line. The rail has been its own scroll container since it became sticky and stays one by default; `railScroll=\"page\"` is the other answer, for a surface whose owner reads a second scrollbar standing beside the results as a second page: no `overflow-y`, no height cap, no gutter, no `overscroll-behavior`, and no bar to dress a port that is not there. The weight is the half that is NOT a deletion, because `\"page\"` is not \"sticky off\": a rail SHORTER than the room under the host's chrome still pins at `railTop`, and only a rail taller than the window goes static — a stuck box that tall is cut off at the foot of the screen, and the page scroll, now the only scroll on the surface, cannot reach its last controls. Which of the two a leaf gets is MEASURED and not guessed from a breakpoint (`useRailFits`: the rail's own height against `window.innerHeight` minus the offset it carries as `scroll-margin-top`, an observer for the element and a listener for the window, and zero refused as a measurement), because the same catalogue draws four facet groups on one section and twenty on the next. 34.5 KB leaves 307 B, then 34.5 -> 34.75 KB for THE THREE THINGS THE OWNER READ AS BROKEN ON A CLIENT STOREFRONT'S CARS LEAF. Measured with dependencies held constant, this package's src before this change and then at it: 34193 -> 34490 B — 297 B, and the old line had 10 B of room left, which is a ceiling that would fail CI on rounding rather than on weight. First, the dictionary's VALUES BOX is a scroll port and was drawing the platform's bar over the row's last column — the count sat under a grey strip. The rail's own scrollbar rule set moves to `./scrollbar.ts` and both ports mount the one hoisted sheet: `scrollbar-gutter: stable` plus a 6px token hairline, the row's count carrying the same measure as padding for the engines that ignore the gutter, and the list opening one step of the scale below the box that filters it. Second, `./focusRing.ts`: the facet controls stamp `data-pointer-focus` on a pointer press and clear it on the first key or on blur, and one rule turns the ring off while that stamp is on. `:focus-visible` was already the only thing drawing it — it is a heuristic, and it fires for a click on a control whose own list has just changed under it, which is every disclosure toggle in the rail. Third, `<PopularValues>` sizes its columns to their words (`inline-size: fit-content`, a scale gap, four columns at most) instead of dividing the whole results pane into three, which printed a make, 300px of nothing, and the next make",
       "path": "dist/default/index.js",
-      "limit": "34.5 KB"
+      "limit": "34.75 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -116,11 +116,11 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@stapel/attributes-react": "^0.17.0",
-    "@stapel/showcase": "^0.3.0",
     "@stapel/core": "^0.26.1",
+    "@stapel/tokens-antd": "^0.19.0",
+    "@stapel/showcase": "^0.3.0",
     "@stapel/image": "^0.4.2",
-    "@stapel/tokens": "^0.8.0",
-    "@stapel/tokens-antd": "^0.18.0"
+    "@stapel/tokens": "^0.8.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

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

package/src/default/FacetGroupControl.tsx

@@ -72,6 +72,18 @@ import type { PickerGroup, PickerOption } from "@stapel/tokens-antd/skin";
 import { controls, cssVar, radii, spacing } from "@stapel/tokens";
 import { featureConfig, featureType } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
+import {
+  POINTER_FOCUS,
+  POINTER_FOCUS_STYLE_HREF,
+  pointerFocusCss,
+} from "./focusRing.js";
+import {
+  RAIL_SCROLLBAR_CLASS,
+  RAIL_STYLE_HREF,
+  SCROLL_GUTTER_INLINE_END,
+  SCROLL_LIST_INSET_BLOCK_START,
+  railScrollbarCss,
+} from "./scrollbar.js";
 import { facetGroupIsVocabularyBacked } from "../state/facets.js";
 import type { FacetGroup, FacetOption } from "../state/facets.js";
 import { translitPrefixMatch } from "../state/translit.js";
@@ -331,6 +343,9 @@ function OptionCount(props: {
   return (
     <Typography.Text
       type="secondary"
+      // The last column of a row that may live inside a scroll port, so it
+      // keeps the port's gutter clear of itself — see `SCROLL_GUTTER_INLINE_END`.
+      style={SCROLL_GUTTER_INLINE_END}
       data-testid={`facet-count-${props.group.slug}-${props.option.value}`}
     >
       {props.option.count === null
@@ -436,6 +451,7 @@ function OptionPill(props: {
       shape="round"
       type={option.selected ? "primary" : "default"}
       aria-pressed={option.selected}
+      {...POINTER_FOCUS}
       style={style}
       data-testid={`facet-option-${group.slug}-${option.value}`}
       data-analytics="none"
@@ -505,12 +521,28 @@ function ChevronGlyph(props: { readonly open: boolean }): ReactElement {
  * The list a dictionary scrolls in. A vocabulary level is 418 makes: without
  * a ceiling the group alone is longer than the rail, and the box that filters
  * it scrolls off the top of the panel while you type into it.
+ *
+ * It is a scroll port, so it takes the panel's two scroll-port rules — see
+ * `./scrollbar.ts`. The bar it used to draw was the PLATFORM's, painted over
+ * the row's last column: on the live storefront «Chery 5» read as «Chery»
+ * with the 5 under a grey strip. `scrollbar-gutter: stable` (in the sheet)
+ * subtracts that space from the content box instead, the row's count carries
+ * the same measure as padding for the engines that ignore the gutter, and the
+ * thumb itself is the skin's hairline rather than chrome.
+ *
+ * The top inset is the other half of the same complaint: the first value was
+ * drawn flush under the box that filters the list and read as clipped BY it.
  */
 const DICTIONARY_LIST: CSSProperties = {
   maxBlockSize: 320,
   overflowY: "auto",
   // The scroll must not clip a focus ring against the panel's edge.
   paddingInlineEnd: spacing[1],
+  paddingBlockStart: SCROLL_LIST_INSET_BLOCK_START,
+  // Stated inline as well as in the sheet: the sheet is what dresses the
+  // thumb, and this is the one property that must hold even if a host never
+  // mounts it.
+  scrollbarGutter: "stable",
 };
 
 /**
@@ -605,7 +637,18 @@ function DictionaryBody(props: {
           {t(SEARCH_I18N_KEYS.facetsDictionaryEmpty)}
         </Typography.Text>
       ) : (
-        <Flex vertical gap={spacing[1]} style={DICTIONARY_LIST}>
+        <Flex
+          vertical
+          gap={spacing[1]}
+          className={RAIL_SCROLLBAR_CLASS}
+          style={DICTIONARY_LIST}
+          data-testid={`facet-dictionary-list-${group.slug}`}
+        >
+          {/* The skin's bar for this port, hoisted and deduped by `href` with
+              the rail's own: a pseudo-element has no inline form. */}
+          <style href={RAIL_STYLE_HREF} precedence="default">
+            {railScrollbarCss()}
+          </style>
           {shown.map((option) => (
             <CheckboxRow
               key={option.value}
@@ -620,6 +663,7 @@ function DictionaryBody(props: {
         <Button
           type="link"
           size="small"
+          {...POINTER_FOCUS}
           style={{ alignSelf: "flex-start", paddingInline: 0 }}
           data-testid={`facet-more-${group.slug}`}
           data-analytics="none"
@@ -703,12 +747,18 @@ function DictionaryField(props: {
         aria-expanded={open}
         aria-haspopup="listbox"
         aria-label={group.label}
+        className={POINTER_FOCUS.className}
+        onPointerDown={POINTER_FOCUS.onPointerDown}
+        onBlur={POINTER_FOCUS.onBlur}
         style={DICTIONARY_FIELD}
         data-testid={`facet-dictionary-field-${group.slug}`}
         data-chosen={chosen.length}
         data-analytics="none"
         data-analytics-reason="opening a filter group is a read, not a flow step"
         onKeyDown={(event) => {
+          // This control owns its own keyboard, so it clears the pointer
+          // stamp itself rather than spreading POINTER_FOCUS whole.
+          POINTER_FOCUS.onKeyDown(event);
           if (event.key === "Escape" && open) {
             event.preventDefault();
             setOpen(false);
@@ -1264,10 +1314,16 @@ export function FacetGroupControl(
       // MARKED, so a storefront's own test can refuse to ship it.
       data-label-source={group.labelSource}
     >
+      {/* The ring the keyboard gets and the mouse does not — one hoisted
+          element for the whole document, deduped by `href`. */}
+      <style href={POINTER_FOCUS_STYLE_HREF} precedence="default">
+        {pointerFocusCss()}
+      </style>
       {props.heading !== false &&
         (disclosure ? (
           <button
             type="button"
+            {...POINTER_FOCUS}
             style={DISCLOSURE_HEADER}
             aria-expanded={open}
             data-testid={`facet-toggle-${group.slug}`}
@@ -1338,6 +1394,7 @@ export function FacetGroupControl(
             <Button
               type="link"
               size="small"
+              {...POINTER_FOCUS}
               style={{ alignSelf: "flex-start", paddingInline: 0 }}
               data-testid={`facet-more-${group.slug}`}
               data-analytics="none"

package/src/default/PopularValues.tsx

@@ -30,6 +30,11 @@ import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Button, Flex, Typography } from "antd";
 import { useT } from "@stapel/core";
 import { breakpoints, spacing } from "@stapel/tokens";
+import {
+  POINTER_FOCUS,
+  POINTER_FOCUS_STYLE_HREF,
+  pointerFocusCss,
+} from "./focusRing.js";
 import type { FacetGroup, FacetOption } from "../state/facets.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
@@ -40,6 +45,16 @@ export const POPULAR_VALUES_LIMIT = 12;
  * without turning a make into a two-line wrap. */
 export const POPULAR_VALUES_COLUMNS = 3;
 
+/**
+ * The ceiling on columns, whatever a host or the ladder asks for.
+ *
+ * Past four the block stops being a table of contents and becomes a grid of
+ * two-word cells: each column is one make and one number, and a fifth column
+ * on a 1100px results pane puts 60px of air between «Toyota 4» and the next
+ * make. Four is where the density still reads as a list.
+ */
+export const POPULAR_VALUES_MAX_COLUMNS = 4;
+
 /**
  * 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
@@ -117,6 +132,38 @@ export function popularOptions(
     .slice(0, limit);
 }
 
+/**
+ * The columns box: as wide as its WORDS, and no wider.
+ *
+ * Multi-column layout divides the container, so three columns of a block that
+ * is handed the whole results pane are three ~360px columns holding «Chery 5»
+ * — which on the storefront printed a make, then 300px of nothing, then the
+ * next make. The owner read it as broken, and it is: nothing about this block
+ * wants the pane's width, it wants its own.
+ *
+ * `inline-size: fit-content` is the whole fix. A multi-column box's max-content
+ * size is `columns × (the widest item) + gaps` — exactly the block's natural
+ * measure — and `fit-content` takes that unless the available space is
+ * smaller, in which case the columns shrink instead of overflowing. The box
+ * stays a block, so it stays flush with the pane's leading edge; the ladder in
+ * the sheet still decides HOW MANY columns, and each one is now sized by the
+ * longest make in it.
+ *
+ * The gap is one step up the scale from the row's own: at content width the
+ * columns sit close enough that the old 16px read as a wrapped line rather
+ * than as a new column.
+ */
+function COLUMNS(count: number | undefined): CSSProperties {
+  return {
+    // The rungs live in the sheet; an inline `column-count` would win against
+    // every one of them, so the responsive arm states none.
+    ...(count === undefined ? {} : { columnCount: count }),
+    columnGap: spacing[6],
+    inlineSize: "fit-content",
+    maxInlineSize: "100%",
+  };
+}
+
 const ROW: CSSProperties = {
   // `break-inside` keeps a value and its count on one line when the browser
   // decides where the column ends.
@@ -171,6 +218,10 @@ export function PopularValues(props: PopularValuesProps): ReactElement | null {
       data-label-source={group.labelSource}
       data-columns={responsive ? "responsive" : String(props.columns ?? POPULAR_VALUES_COLUMNS)}
     >
+      {/* The ring the keyboard gets and the mouse does not. */}
+      <style href={POINTER_FOCUS_STYLE_HREF} precedence="default">
+        {pointerFocusCss()}
+      </style>
       {/* 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. */}
@@ -184,20 +235,22 @@ export function PopularValues(props: PopularValuesProps): ReactElement | null {
       )}
       <div
         {...(responsive ? { "data-popular-columns": "" } : {})}
-        style={{
-          // 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],
-        }}
+        data-testid={`popular-columns-${group.slug}`}
+        style={COLUMNS(
+          responsive
+            ? undefined
+            : Math.min(
+                props.columns ?? POPULAR_VALUES_COLUMNS,
+                POPULAR_VALUES_MAX_COLUMNS
+              )
+        )}
       >
         {options.map((option) => (
           <div key={option.value} style={ROW}>
             <Button
               type="link"
               size="small"
+              {...POINTER_FOCUS}
               style={{ paddingInline: 0, height: "auto" }}
               data-testid={`popular-value-${group.slug}-${option.value}`}
               data-analytics="none"
@@ -221,6 +274,7 @@ export function PopularValues(props: PopularValuesProps): ReactElement | null {
         <Button
           type="link"
           size="small"
+          {...POINTER_FOCUS}
           style={{ alignSelf: "flex-start", paddingInline: 0 }}
           data-testid={`popular-all-${group.slug}`}
           data-analytics="none"