@stapel/search-react 0.38.0 → 0.40.0

package/dist/default/swatches.js

@@ -0,0 +1,200 @@
+/**
+ * A COLOUR FACET SHOWS THE COLOUR.
+ *
+ * The reference's colour group draws a filled dot beside every value; ours
+ * drew the word and made the buyer read it (deep/elektronika-telefony.md §3,
+ * the one rail regression that pass found). A colour is the one attribute
+ * whose label is strictly worse than the thing itself — "silver" versus
+ * "gold" in a catalogue's own transliteration is a paragraph of prose for a difference a 10px dot settles.
+ *
+ * Two questions, and each is answered conservatively, because both failures
+ * are visible on a shopper's screen:
+ *
+ *  1. **is this axis a colour?** — {@link isColorAxis}, from the slug the
+ *     catalogue mapped the axis to (and the address key, and `axis_role` if a
+ *     schema ever carries one). A guess on the slug, exactly like
+ *     `looksLikeExclusiveAxisSlug` next door: nothing on the wire marks an
+ *     axis "colour", and inspecting the VALUES for colour-ish names would put
+ *     dots on a paint-brand axis whose makes are called `Bordeaux`;
+ *  2. **which colour is this value?** — {@link swatchColor}, and the honest
+ *     answer is usually "nobody said". A value code is a catalogue's own term
+ *     (`chernyy`, `dark-slate-2`) and neither the answer, the feature schema
+ *     nor the vocabulary endpoint carries a hue for it. So the pair paints a
+ *     dot only where the code IS a colour by a name it can resolve — the
+ *     design system's own colour roles first (§68: one neutral vocabulary of
+ *     ROLES, and it deliberately ships no hue ramp), then CSS's own colour
+ *     keywords, then a code that spells the hue out in hex — and draws
+ *     NOTHING otherwise. An invented mapping from a transliterated Russian
+ *     word to a hex value is data this pair does not have.
+ */
+import { cssVar } from "@stapel/tokens";
+/**
+ * The control-type tails a catalogue hangs on an axis slug when one feature
+ * type is not enough to tell two mappings apart (`color_ref_select` is the
+ * live phones leaf's own colour axis; `color_select` and `color_multi` are
+ * the same axis under a different editor).
+ *
+ * Stripped before the head is read, so the control a value is PICKED with
+ * cannot change what the value IS.
+ */
+const CONTROL_TAILS = [
+    "ref_hierarchical_select",
+    "hierarchical_select",
+    "ref_select",
+    "multiselect",
+    "multi_select",
+    "select",
+    "multi",
+    "picker",
+    "field",
+];
+function normalizeSlug(slug) {
+    let normalized = slug.toLowerCase().replace(/-/g, "_");
+    for (const tail of CONTROL_TAILS) {
+        if (normalized.endsWith(`_${tail}`)) {
+            normalized = normalized.slice(0, -(tail.length + 1));
+            break;
+        }
+    }
+    return normalized;
+}
+/** The two spellings, and only as the slug's HEAD segment: `color_fridge` is
+ * the colour of a fridge and `colorado_region` is a place. */
+const COLOR_HEADS = new Set(["color", "colour"]);
+function headIsColor(slug) {
+    if (slug === undefined || slug === "")
+        return false;
+    const normalized = normalizeSlug(slug);
+    const head = normalized.split("_")[0] ?? "";
+    return COLOR_HEADS.has(head);
+}
+/**
+ * Is this axis a colour vocabulary?
+ *
+ * Three sources, in the order of how much authority they carry:
+ *
+ *  - `axis_role` — the schema SAYING what an axis is, which is the only
+ *    non-guess available. The canon's role vocabulary is closed and has no
+ *    colour in it yet (`make`/`model`/`generation`/`year`/`mileage`), so this
+ *    arm reads the field as text and is dead until the canon grows one. It is
+ *    written now so that the day it does, nothing here has to change;
+ *  - the axis slug, and the ADDRESS key beside it — the live phones leaf maps
+ *    its colour to `color_ref_select` and publishes it as `color`, so either
+ *    spelling alone would miss half the deployments.
+ */
+export function isColorAxis(group) {
+    const role = group.feature?.["axis_role"];
+    if (typeof role === "string" && COLOR_HEADS.has(role.toLowerCase()))
+        return true;
+    return headIsColor(group.slug) || headIsColor(group.urlKey);
+}
+/**
+ * The design system's colour ROLES, for a value code that names one.
+ *
+ * The fleet's token vocabulary is neutral and role-shaped on purpose (§68):
+ * there is no `red`, no `blue`, and no ramp — so a colour axis whose values
+ * are hues matches nothing here, which is the correct answer rather than a
+ * gap. What does match is a catalogue that codes STATES as colours (a
+ * `status` axis mapped under a colour slug), and those take the brand's own
+ * value in both themes rather than a frozen hex.
+ */
+const TOKEN_ROLE_SWATCHES = {
+    brand: cssVar("brand"),
+    error: cssVar("error"),
+    info: cssVar("info"),
+    link: cssVar("link"),
+    success: cssVar("success"),
+    surface: cssVar("surface"),
+    text: cssVar("text"),
+};
+/**
+ * CSS's own colour keywords — a NAME that matches, in the vocabulary every
+ * browser already agrees on.
+ *
+ * The basic sixteen plus the extended keywords a product catalogue actually
+ * uses. Deliberately not the full 148: every entry here is a promise that a
+ * value code spelled that way means that colour, and `rebeccapurple` in a
+ * phone catalogue is far likelier to be somebody's model name.
+ */
+const CSS_COLOR_KEYWORDS = [
+    "aqua",
+    "beige",
+    "black",
+    "blue",
+    "brown",
+    "chocolate",
+    "coral",
+    "crimson",
+    "cyan",
+    "fuchsia",
+    "gold",
+    "gray",
+    "green",
+    "grey",
+    "indigo",
+    "ivory",
+    "khaki",
+    "lavender",
+    "lime",
+    "magenta",
+    "maroon",
+    "navy",
+    "olive",
+    "orange",
+    "orchid",
+    "pink",
+    "plum",
+    "purple",
+    "red",
+    "salmon",
+    "sand",
+    "sienna",
+    "silver",
+    "skyblue",
+    "tan",
+    "teal",
+    "tomato",
+    "turquoise",
+    "violet",
+    "wheat",
+    "white",
+    "yellow",
+];
+const CSS_COLOR_SET = new Set(CSS_COLOR_KEYWORDS);
+/** `#abc`, `#aabbcc`, `#aabbccdd` — a catalogue that codes the hue itself. */
+const HEX = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/**
+ * The CSS colour one value code names, or `null` for "nobody said".
+ *
+ * `null` is the ordinary answer and the row then draws no dot at all: a grey
+ * placeholder beside eleven values would say "these are all the same colour",
+ * which is worse than the word on its own.
+ *
+ * The code is read as written apart from case and separators — `dark_blue`
+ * and `dark-blue` are one code and neither is a CSS keyword, so both get
+ * nothing. Only a code that IS a name resolves.
+ */
+export function swatchColor(code) {
+    const raw = code.trim();
+    if (raw === "")
+        return null;
+    if (HEX.test(raw))
+        return raw;
+    const normalized = raw.toLowerCase().replace(/[-_\s]/g, "");
+    const role = TOKEN_ROLE_SWATCHES[normalized];
+    if (role !== undefined)
+        return role;
+    return CSS_COLOR_SET.has(normalized) ? normalized : null;
+}
+/**
+ * The dot a value gets when this axis is a colour AND the value names one.
+ * `null` everywhere else, which is most of the time — see {@link swatchColor}.
+ */
+export function facetSwatch(group, code) {
+    return isColorAxis(group) ? swatchColor(code) : null;
+}
+/** The swatch's own size, in CSS pixels: a dot beside a line of text, sized
+ * to the x-height rather than to the control, so it reads as part of the
+ * label and not as a second checkbox. */
+export const SWATCH_SIZE = 12;
+//# sourceMappingURL=swatches.js.map

package/dist/default/swatches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swatches.js","sourceRoot":"","sources":["../../src/default/swatches.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/search-react 0.38.0
+# @stapel/search-react 0.40.0
 
 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,
@@ -85,9 +85,9 @@ const { tracked } = useTracked();
 - search.language-select → <LanguageSelect> [offered|from-a-link]  demo/LanguageSelect.demo.tsx
 - search.location-summary → <LocationSummaryLine> [everywhere|placed|narrowed|long-place|wide]  demo/LocationSummaryLine.demo.tsx
 - search.other-categories-line → <OtherCategoriesLine> [line|narrow|empty]  demo/OtherCategoriesLine.demo.tsx
-- search.page → <SearchPage> [desktop|phone|catalogue-leaf|under-a-header|system-scrollbar|legacy-rhythm|filters-header-navigates|unreadable-link]  demo/SearchPage.demo.tsx
+- search.page → <SearchPage> [desktop|phone|catalogue-leaf|under-a-header|toolbar-not-pinned|rail-on-a-panel|system-scrollbar|legacy-rhythm|filters-header-navigates|unreadable-link]  demo/SearchPage.demo.tsx
 - search.page-size-select → <PageSizeSelect> [ladder|off-ladder]  demo/PageSizeSelect.demo.tsx
-- search.partition-chips → <PartitionChips> [parent|counted|child]  demo/PartitionChips.demo.tsx
+- search.partition-chips → <PartitionChips> [parent|counted|pointer|child]  demo/PartitionChips.demo.tsx
 - search.popular-values → <PopularValues> [desktop|responsive|narrow-column]  demo/PopularValues.demo.tsx
 - search.range-filter-row → <RangeFilterRow> [untouched|applied]  demo/RangeFilterRow.demo.tsx
 - search.ranking-pane → <RankingDisclosurePane> [desktop|phone]  demo/RankingDisclosurePane.demo.tsx

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.38.0",
+  "version": "0.40.0",
   "backend": {
     "module": "stapel-search",
     "contract": ">=0.16 <0.17"
@@ -582,6 +582,8 @@
         "phone",
         "catalogue-leaf",
         "under-a-header",
+        "toolbar-not-pinned",
+        "rail-on-a-panel",
         "system-scrollbar",
         "legacy-rhythm",
         "filters-header-navigates",
@@ -611,6 +613,7 @@
       "variants": [
         "parent",
         "counted",
+        "pointer",
         "child"
       ],
       "source": "demo/PartitionChips.demo.tsx"

package/nav-manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/search-react",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "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",
+      "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",
       "path": "dist/default/index.js",
-      "limit": "32.75 KB"
+      "limit": "34 KB"
     },
     {
       "name": "router — the react-router binding is opt-in; the main entry must never pull a router",
@@ -115,8 +115,8 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/core": "^0.26.1",
     "@stapel/attributes-react": "^0.17.0",
+    "@stapel/core": "^0.26.1",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.8.0",

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.38.0",
+  "version": "0.40.0",
   "defined": [],
   "flows": []
 }

package/src/default/FacetGroupControl.tsx

@@ -67,6 +67,7 @@ import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
 import { SkinPickerSheet } from "@stapel/tokens-antd/skin";
+import { SWATCH_SIZE, facetSwatch } from "./swatches.js";
 import type { PickerGroup, PickerOption } from "@stapel/tokens-antd/skin";
 import { controls, cssVar, radii, spacing } from "@stapel/tokens";
 import { featureConfig, featureType } from "@stapel/attributes-react";
@@ -342,6 +343,42 @@ function OptionCount(props: {
 /** The indent one level of a hierarchical facet is drawn with. */
 const NEST_STEP = spacing[5];
 
+/**
+ * The colour a value IS, drawn beside the word for it — see `./swatches.ts`.
+ *
+ * `aria-hidden`, and it never replaces the label: a dot is a second way to
+ * read a row that already reads, so a screen reader and a monochrome display
+ * lose nothing. The hairline is the panel's own border role, because a white
+ * swatch on a white rail is otherwise an empty hole.
+ */
+function Swatch(props: {
+  readonly group: FacetGroup;
+  readonly value: string;
+}): ReactElement | null {
+  const color = facetSwatch(props.group, props.value);
+  if (color === null) return null;
+  return (
+    <span
+      aria-hidden="true"
+      data-testid={`facet-swatch-${props.group.slug}-${props.value}`}
+      data-swatch={color}
+      style={{
+        display: "inline-block",
+        inlineSize: SWATCH_SIZE,
+        blockSize: SWATCH_SIZE,
+        flex: "0 0 auto",
+        borderRadius: radii.full,
+        background: color,
+        border: `1px solid ${cssVar("border")}`,
+        // The dot sits ON the text line rather than on the box's baseline,
+        // which is what keeps a 12px circle centred against a 14px label.
+        verticalAlign: "-0.125em",
+        marginInlineEnd: spacing[1],
+      }}
+    />
+  );
+}
+
 function CheckboxRow(props: {
   readonly group: FacetGroup;
   readonly node: FacetOptionNode;
@@ -369,6 +406,7 @@ function CheckboxRow(props: {
           props.onToggle(group.slug, node.option.value);
         }}
       >
+        <Swatch group={group} value={node.option.value} />
         {node.option.label}
       </Checkbox>
       <OptionCount group={group} option={node.option} />
@@ -406,6 +444,7 @@ function OptionPill(props: {
         props.onToggle(group.slug, option.value);
       }}
     >
+      <Swatch group={group} value={option.value} />
       {option.count === null ? option.label : `${option.label} ${option.count}`}
     </Button>
   );

package/src/default/FacetPanelPane.tsx

@@ -96,7 +96,7 @@ import {
   LoadList,
   SkinTheme,
 } from "@stapel/tokens-antd/skin";
-import { spacing } from "@stapel/tokens";
+import { cssVar, spacing } from "@stapel/tokens";
 import { featureName } from "@stapel/attributes-react";
 import type { FeatureDef } from "@stapel/attributes-react";
 import type { SearchGeo } from "../api/types.js";
@@ -226,7 +226,32 @@ export interface GeoFilterSlotProps {
   readonly onChange: (geo: SearchGeo | null) => void;
 }
 
+/**
+ * WHAT THE FILTER PANEL'S OWN BODY PAINTS — see
+ * {@link FacetPanelPaneProps.railSurface}.
+ */
+export type SearchRailSurface = "flat" | "panel";
+
 export interface FacetPanelPaneProps extends ThemeModeProp {
+  /**
+   * WHAT THE PANEL'S OWN BODY PAINTS. Default `"flat"`.
+   *
+   *  - `"flat"` — nothing. The panel is a column of controls standing on the
+   *    page's own ground, and it takes only the text colour it needs
+   *    (`var(--stapel-text)`), which a bare surface does not set;
+   *  - `"panel"` — the raised container ground this pane painted until now.
+   *
+   * The default changed, and the measurement is why: on the stand's dark theme
+   * the rail was a **270 x 1539** filled slab with no radius and no border,
+   * standing on the page ground — a card shape with none of a card's edges,
+   * running the whole height of the feed beside it. The same read produced the
+   * same verdict for `categories-react`'s grid, strip and breadcrumbs, and the
+   * answer there was the same one: draw the controls, not a box around them.
+   *
+   * `"panel"` is the old arm kept whole, for a deployment whose page ground is
+   * an image or whose layout genuinely wants the filters on their own sheet.
+   */
+  readonly railSurface?: SearchRailSurface;
   /** The category's feature schema — the source of option LABELS, of which
    * slugs get a numeric range row, and of which slugs are a filter at all
    * (`isFacetableFeature`: an `imei` is counted and is not one). */
@@ -407,6 +432,9 @@ function RailFooterBar(props: {
   /** `"sticky"` pins it to the scroll port's floor; `"static"` lets it sit
    * after the last group. See {@link FacetPanelPaneProps.footerBar}. */
   readonly position: "sticky" | "static";
+  /** What the panel around it paints, so a pinned bar takes the SAME ground
+   * rather than deciding one of its own. See {@link FacetPanelPaneProps.railSurface}. */
+  readonly railSurface: SearchRailSurface;
 }): ReactElement | null {
   const t = useT();
   const tPlural = useTPlural();
@@ -430,9 +458,25 @@ function RailFooterBar(props: {
       data-testid="facets-footer-bar"
       data-position={props.position}
       style={{
-        ...(props.position === "sticky" ? { position: "sticky", bottom: 0 } : {}),
-        // Opaque, or the options scrolling under the bar read THROUGH it.
-        background: token.colorBgContainer,
+        ...(props.position === "sticky"
+          ? {
+              position: "sticky",
+              bottom: 0,
+              /* THE GROUND IT IS ON, and only where it has to be opaque.
+                 The bar used to paint antd's `colorBgContainer` in BOTH arms:
+                 a second opinion about a colour its parent already decided,
+                 and — since the panel's own body went flat — a lighter strip
+                 standing across the foot of the rail on the stand's dark
+                 theme. It now paints the same token the panel does and only
+                 in the arm that is pinned over its own scroll port, where a
+                 transparent floor lets the options read THROUGH it. The
+                 static arm has nothing scrolling under it and paints
+                 nothing. */
+              background: cssVar(
+                props.railSurface === "panel" ? "surface-raised" : "surface"
+              ),
+            }
+          : {}),
         borderBlockStart: `1px solid ${token.colorSplit}`,
         paddingBlockStart: spacing[2],
         display: "flex",
@@ -633,8 +677,19 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
         ? "none"
         : props.footerBar;
 
+  /* The panel's own ground — see `railSurface`. `"bare"` paints NOTHING, text
+     colour included, so the flat arm states the one property it still needs;
+     the theme's own custom property, so it follows the brand and the dark side
+     rather than freezing whichever mode mounted first. */
+  const railSurface: SearchRailSurface = props.railSurface ?? "flat";
+
   return (
-    <SkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+    <SkinTheme
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+      {...(railSurface === "flat"
+        ? { surface: "bare" as const, style: { color: cssVar("text") } }
+        : {})}
+    >
       <FacetPanel
         {...(props.categoryFeatures !== undefined
           ? { categoryFeatures: props.categoryFeatures }
@@ -1155,6 +1210,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 activeFilters={bag.activeFilters}
                 clearAll={bag.clearAll}
                 position={footerBar}
+                railSurface={railSurface}
               />
             )}
           </Flex>