@stapel/search-react 0.39.0 → 0.41.0

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>

package/src/default/SearchPage.tsx

@@ -82,6 +82,7 @@ import type {
   CategoryFilterSlotProps,
   FacetPanelPaneProps,
   GeoFilterSlotProps,
+  SearchRailSurface,
 } from "./FacetPanelPane.js";
 import { FilterChips } from "./FilterChips.js";
 import { LocationSummaryLine } from "./LocationSummaryLine.js";
@@ -394,6 +395,9 @@ export function railStyle(top: number | string | undefined): CSSProperties {
  * cannot push the grid wider than its column. */
 const RESULTS_COLUMN: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
 
+/** A wrapper that names a slot without occupying one — see `resultsHeader`. */
+const CONTENTS_BOX: CSSProperties = { display: "contents" };
+
 /* ── THE RHYTHM: ONE GAP BETWEEN BLOCKS, SAID ONCE ─────────────────────────
  *
  * This page is an assembly of BLOCKS — the query box, the breadcrumb, the
@@ -785,6 +789,16 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * page was measured on.
    */
   readonly railScrollbar?: SearchRailScrollbar;
+  /**
+   * WHAT THE FILTER PANEL'S OWN BODY PAINTS. Default `"flat"`.
+   *
+   * Handed straight to {@link FacetPanelPaneProps.railSurface}, in the column
+   * and in the phone sheet alike. `"flat"` draws the controls and no box
+   * around them (the stand's dark theme read the old ground as a 270 x 1539
+   * filled slab with no radius and no border, standing on the page ground);
+   * `"panel"` restores the raised container this page painted until now.
+   */
+  readonly railSurface?: SearchRailSurface;
   /**
    * WHERE the space between this page's blocks comes from. Default `"token"`.
    *
@@ -822,6 +836,28 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * the layout put under their thumb.
    */
   readonly stickyToolbar?: SearchToolbarPin;
+  /**
+   * PIN the results toolbar by default, on a fine pointer, at {@link railTop}.
+   * Default `true`.
+   *
+   * {@link stickyToolbar} is the same pin asked for explicitly, and it existed
+   * for a release without a single deployment turning it on — a default nobody
+   * sets 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 the same without being asked:
+   *
+   *  - it pins at `railTop`, so the two columns clear the host's header by the
+   *    same edge and there is no second number to keep in step;
+   *  - it is a `@media (pointer: fine)` rule, so a phone keeps its toolbar in
+   *    flow — a pinned bar over a 390px viewport spends the fold on chrome;
+   *  - the row reserves its own height whether or not it pins, so nothing in
+   *    the feed moves when the rule engages.
+   *
+   * `stickyToolbar` still wins where it is given (it pins on every pointer, at
+   * its own offset). `false` turns the default off and leaves the row static —
+   * for a surface that draws a bar of its own over the page.
+   */
+  readonly toolbarSticky?: boolean;
   /**
    * The host's own exits from an empty result — sibling sections with their
    * counts. A SLOT for the same reason `breadcrumb` is one: walking the tree
@@ -990,8 +1026,10 @@ interface SearchPageBodyProps {
   readonly filtersLayout?: SearchFiltersLayout;
   readonly railTop?: number | string;
   readonly railScrollbar?: SearchRailScrollbar;
+  readonly railSurface?: SearchRailSurface;
   readonly blockRhythm?: SearchBlockRhythm;
   readonly stickyToolbar?: SearchToolbarPin;
+  readonly toolbarSticky?: boolean;
   readonly defaultFiltersOpen?: boolean;
   readonly filtersOpen?: boolean;
   readonly onFiltersOpenChange?: (
@@ -1178,6 +1216,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         <FacetPanelPane
           {...(layout === "sheet" ? { heading: null } : {})}
           {...(footerBar !== undefined ? { footerBar } : {})}
+          {...(props.railSurface !== undefined
+            ? { railSurface: props.railSurface }
+            : {})}
           dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "sheet" : "field")}
           // `??` would treat an explicit `null` ("never fold") the same as
           // "not set": `visibleGroups` uses `null` as a real value, unlike
@@ -1250,6 +1291,10 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     </Flex>
   );
 
+  /* ONE OFFSET FOR BOTH COLUMNS. The rail's sticky top edge and the toolbar's
+     are the same edge — the foot of whatever chrome the host pinned above this
+     page — so `railTop` feeds both rather than the page asking for the number
+     twice and letting the two halves disagree. */
   const results = (
     <SearchResultsPane
       toolbar={toolbar}
@@ -1258,6 +1303,10 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(props.stickyToolbar !== undefined
         ? { stickyToolbar: props.stickyToolbar }
         : {})}
+      {...(props.toolbarSticky !== undefined
+        ? { toolbarSticky: props.toolbarSticky }
+        : {})}
+      {...(props.railTop !== undefined ? { toolbarTop: props.railTop } : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
       {...(props.wrapResults !== undefined ? { wrapResults: props.wrapResults } : {})}
@@ -1363,7 +1412,25 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           the written decision, not an oversight: a page with nothing to say
           about location says nothing rather than reserving a blank row. */}
       {props.resultsHeader !== undefined && (
-        <div data-testid="search-results-header">{props.resultsHeader}</div>
+        /* NO BOX OF ITS OWN (`display: contents`). The slot is a NODE, and a
+           node that renders nothing is indistinguishable from one that renders
+           something until React has run it — so the wrapper was mounted on the
+           prop alone and stood in this column as a 1392 x 0 element whenever
+           the host's header had nothing to say. Inside the block rhythm an
+           empty child is not free: the column's `gap` is charged on BOTH sides
+           of it, so the distance between the two real blocks around it
+           measured 64px where 32 is declared, on every feed page (owner's
+           tidiness probe on the stand).
+
+           `display: contents` generates no box at all: with nothing inside,
+           there is no flex item and no gap; with something inside, the host's
+           own element IS the column's child and takes exactly one gap. The
+           `data-testid` survives either way, and the consumer stylesheet's
+           stand-in (`[data-testid="search-results-header"]:empty{display:none}`)
+           can go. */
+        <div style={CONTENTS_BOX} data-testid="search-results-header">
+          {props.resultsHeader}
+        </div>
       )}
 
       {/* What the search is NARROWED to, above the results, each constraint
@@ -1502,8 +1569,10 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     filtersLayout,
     railTop,
     railScrollbar,
+    railSurface,
     blockRhythm,
     stickyToolbar,
+    toolbarSticky,
     defaultFiltersOpen,
     filtersOpen,
     onFiltersOpenChange,
@@ -1568,8 +1637,10 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}
           {...(railTop !== undefined ? { railTop } : {})}
           {...(railScrollbar !== undefined ? { railScrollbar } : {})}
+          {...(railSurface !== undefined ? { railSurface } : {})}
           {...(blockRhythm !== undefined ? { blockRhythm } : {})}
           {...(stickyToolbar !== undefined ? { stickyToolbar } : {})}
+          {...(toolbarSticky !== undefined ? { toolbarSticky } : {})}
           {...(defaultFiltersOpen !== undefined ? { defaultFiltersOpen } : {})}
           {...(filtersOpen !== undefined ? { filtersOpen } : {})}
           {...(onFiltersOpenChange !== undefined ? { onFiltersOpenChange } : {})}

package/src/default/SearchResultsPane.tsx

@@ -25,7 +25,7 @@
  *    when the answer actually has another page in some direction.
  */
 import type { CSSProperties, ReactElement, ReactNode } from "react";
-import { Flex, Typography } from "antd";
+import { Flex, Typography, theme as antdTheme } from "antd";
 import { errorCode, useT, useTPlural } from "@stapel/core";
 import {
   EmptyState,
@@ -139,6 +139,76 @@ export interface SearchToolbarPin {
   readonly top?: number | string;
 }
 
+/**
+ * The class the DEFAULT pin's rules are hung on — the media-gated half of
+ * {@link SearchResultsPaneProps.toolbarSticky}.
+ *
+ * A class and a sheet rather than an inline style, for the one reason a sheet
+ * is ever right here: the pin is `@media (pointer: fine)` and a media query
+ * cannot be said in a `style` attribute. A pinned sort row is a desktop
+ * affordance — a phone's toolbar is already one tap from the top of a short
+ * scroll, and a bar standing over a 390px viewport spends the fold on chrome
+ * the reader did not ask for (REPORT §24, Surface 2: what the reference pins
+ * is the DESKTOP feed's sort row).
+ */
+export const RESULTS_TOOLBAR_STICKY_CLASS = "stapel-search-results-toolbar-sticky";
+
+/** The custom property the default pin reads its offset from. */
+export const RESULTS_TOOLBAR_TOP_VAR = "--stapel-search-toolbar-top";
+
+/** The `href` the hoisted toolbar sheet is deduplicated by. */
+export const RESULTS_TOOLBAR_STYLE_HREF = "stapel-search-toolbar";
+
+/**
+ * The default pin's rule set.
+ *
+ * Everything {@link toolbarPinStyle} writes inline, said once in a sheet and
+ * gated on a fine pointer — the offset arrives per instance through
+ * {@link RESULTS_TOOLBAR_TOP_VAR}, which is how one static rule serves a page
+ * whose header height only the host knows. `0px` is the fallback, which is
+ * where a page with no chrome above it pins.
+ */
+export function toolbarStickyCss(): string {
+  const bar = `.${RESULTS_TOOLBAR_STICKY_CLASS}`;
+  return (
+    `@media (pointer:fine){` +
+    `${bar}{position:sticky;top:var(${RESULTS_TOOLBAR_TOP_VAR},0px);` +
+    // Over the cards, under the page's own chrome — and under antd's popups,
+    // so the sort select still opens over its own bar. Opaque, or the cards
+    // scroll THROUGH the row.
+    `z-index:1;background:${cssVar("surface")}}}`
+  );
+}
+
+/**
+ * The toolbar row's own block-size, reserved from the FIRST frame.
+ *
+ * The same discipline — and the same arithmetic — as `chipRowMinHeight`: a
+ * NUMBER OUT OF THE THEME rather than a constant, because the shared
+ * `SkinTheme` raises `controlHeight` to the 44px touch floor below the tablet
+ * breakpoint and a hard-coded reserve is then right on one surface and wrong
+ * on the other.
+ *
+ * Why a row that is already this tall states it anyway: the row's contents
+ * arrive in two frames — the count lands with the answer, and a sort select
+ * whose options are still loading measures its placeholder — so the box a
+ * pinned bar occupies must not be a consequence of what is inside it. A
+ * reserve makes the height a constant before and after the pin engages, which
+ * is what "no layout shift when it pins" means in a `position: sticky` world:
+ * the sticky box keeps its place in flow, so the only way it can move the feed
+ * is by changing its own height.
+ */
+export function toolbarRowMinHeight(controlHeight: number): number {
+  return controlHeight + spacing[1] * 2;
+}
+
+/** A CSS length from a prop that is a number of pixels or a string as written
+ * (a `var()`, a `calc()`, `"4rem"`) — the rule `railStyle` follows. */
+function toolbarTopLength(top: number | string | undefined): string {
+  if (top === undefined) return "0px";
+  return typeof top === "number" ? `${String(top)}px` : top;
+}
+
 /**
  * The controls' own line: it may not become two.
  *
@@ -598,6 +668,36 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * pins it where it stands.
    */
   readonly stickyToolbar?: SearchToolbarPin;
+  /**
+   * PIN the toolbar row by default, on a fine pointer. Default `true`.
+   *
+   * The same argument as {@link stickyToolbar} and none of the wiring: a
+   * catalogue page is thirty cards long, the control that reorders them is at
+   * the top of it, and by the fourth row the sort is a screenful above the
+   * list it sorts. The reference pins its sort bar once a reader has scrolled
+   * into results (REPORT §24, Surface 2); this pair had the mechanism and made
+   * every host ask for it, so no deployment had it.
+   *
+   * What the default does that the explicit prop cannot: it is a `@media
+   * (pointer: fine)` rule (see {@link toolbarStickyCss}), so a phone — where
+   * a pinned bar costs a fifth of the fold and the feed is a flick long —
+   * keeps its toolbar in flow. `stickyToolbar` stays the host's own
+   * instruction and is honoured on every pointer; passing it takes this
+   * default out of play, so the two can never both be on one row.
+   *
+   * `false` leaves the row exactly where it stood: no class, no sheet, no
+   * custom property.
+   */
+  readonly toolbarSticky?: boolean;
+  /**
+   * WHERE the default pin's top edge is — the results column's half of
+   * `<SearchPage railTop>`, and the same value.
+   *
+   * A number is pixels; a string is taken as written, so
+   * `toolbarTop="var(--stapel-header-height)"` reads the height
+   * `<PublicShell>` publishes rather than restating it. Default `0`.
+   */
+  readonly toolbarTop?: number | string;
   /**
    * The category's feature schema, used ONLY to name an applied filter in the
    * empty state's exits ("Without Brand" rather than "Without vendor").
@@ -706,6 +806,34 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
   // not, and `headingVisible` overrides either way — see that prop.
   const compactHeadingSeen = props.headingVisible ?? props.heading !== undefined;
   const toolbarPin = toolbarPinStyle(props.stickyToolbar);
+  // The chips' own height, from the theme they are drawn in — see
+  // `toolbarRowMinHeight`.
+  const { token } = antdTheme.useToken();
+  /* The DEFAULT pin, and the host's explicit one takes precedence: a row
+     carrying both would be pinned twice at two offsets, and which one wins
+     would be whichever declaration the cascade happened to resolve last. */
+  const defaultPin = props.stickyToolbar === undefined && props.toolbarSticky !== false;
+  const toolbarClass = defaultPin
+    ? `${RESULTS_TOOLBAR_CLASS} ${RESULTS_TOOLBAR_STICKY_CLASS}`
+    : RESULTS_TOOLBAR_CLASS;
+  /* The reserve is written whether or not the row pins, and that is the
+     point: a height that only exists while pinned is a height that changes
+     when the pin engages. */
+  const toolbarBox: CSSProperties = {
+    minBlockSize: toolbarRowMinHeight(token.controlHeight),
+    ...(defaultPin
+      ? ({ [RESULTS_TOOLBAR_TOP_VAR]: toolbarTopLength(props.toolbarTop) } as CSSProperties)
+      : {}),
+    ...toolbarPin,
+  };
+  /* Hoisted and deduped by `href` (React 19), and not mounted at all when
+     nothing carries the class — a sheet whose only selector is a class no
+     node has is dead weight in the document. */
+  const toolbarSheet = defaultPin ? (
+    <style href={RESULTS_TOOLBAR_STYLE_HREF} precedence="default">
+      {toolbarStickyCss()}
+    </style>
+  ) : null;
   const columnRules =
     props.columns === undefined || props.layout === "list"
       ? null
@@ -739,6 +867,7 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
         ...(maxWidth !== null ? { maxWidth } : {}),
       }}
     >
+      {toolbarSheet}
       <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
         {(bag) => (
           <Flex
@@ -773,9 +902,9 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                   {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
                 </Typography.Title>
                 <div
-                  className={RESULTS_TOOLBAR_CLASS}
+                  className={toolbarClass}
                   data-testid="search-results-toolbar"
-                  style={{ ...COMPACT_TOOLBAR, ...toolbarPin }}
+                  style={{ ...COMPACT_TOOLBAR, ...toolbarBox }}
                 >
                   {props.toolbar}
                 </div>
@@ -800,9 +929,9 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                 <Flex
                   align="center"
                   gap={spacing[3]}
-                  className={RESULTS_TOOLBAR_CLASS}
+                  className={toolbarClass}
                   data-testid="search-results-toolbar"
-                  style={{ ...TOOLBAR_ROW, ...toolbarPin }}
+                  style={{ ...TOOLBAR_ROW, ...toolbarBox }}
                 >
                   {/* The elastic half, present whether or not there is a
                       count in it — see TOOLBAR_LEAD. It is what holds the

package/src/default/index.ts

@@ -86,7 +86,12 @@ export {
   RESULTS_COLUMNS_CLASS,
   RESULTS_COLUMNS_STYLE_HREF,
   RESULTS_TOOLBAR_CLASS,
+  RESULTS_TOOLBAR_STICKY_CLASS,
+  RESULTS_TOOLBAR_STYLE_HREF,
+  RESULTS_TOOLBAR_TOP_VAR,
   resultsColumnsCss,
+  toolbarRowMinHeight,
+  toolbarStickyCss,
 } from "./SearchResultsPane.js";
 export type {
   ResultsColumns,
@@ -151,6 +156,15 @@ export type {
   FacetOptionNode,
 } from "./FacetGroupControl.js";
 
+export {
+  SWATCH_SIZE,
+  facetSwatch,
+  isColorAxis,
+  swatchColor,
+  termHue,
+} from "./swatches.js";
+export type { ColorAxisLike, TermExtra } from "./swatches.js";
+
 // ── the browse surfaces a storefront PLACES (this pair does not lay them
 //    out: where a popular-values block or a partition row belongs on a
 //    category page is the page's decision) ──────────────────────────────────
@@ -183,6 +197,7 @@ export type {
   FacetPanelPaneProps,
   CategoryFilterSlotProps,
   GeoFilterSlotProps,
+  SearchRailSurface,
 } from "./FacetPanelPane.js";
 
 export { RankingDisclosurePane, RANKING_MAX_WIDTH } from "./RankingDisclosurePane.js";