@stapel/search-react 0.32.7 → 0.33.0

package/src/default/SearchPage.tsx

@@ -94,6 +94,7 @@ import { SearchResultsPane } from "./SearchResultsPane.js";
 import type {
   ResultsColumns,
   SearchResultsWrapper,
+  SearchToolbarPin,
 } from "./SearchResultsPane.js";
 import { SortSelect } from "./SortSelect.js";
 import { SEARCH_BUILTIN_VIEWS, ViewSwitch, resolveView } from "./ViewSwitch.js";
@@ -283,6 +284,24 @@ const RAIL: CSSProperties = {
   paddingBlockEnd: spacing[2],
 };
 
+/**
+ * The rail with a host's own offset under it.
+ *
+ * `top` and the height cap move TOGETHER, and that is the whole reason this is
+ * a function rather than one property: a rail pushed 64px down the window whose
+ * cap is still `100dvh` ends 64px past the foot of the screen, so its last
+ * control is unreachable — the internal scroll has scrolled past the window.
+ *
+ * A number is pixels; a string is taken as written, so
+ * `railTop="var(--stapel-header-height)"` reads the height `<PublicShell>`
+ * publishes instead of restating it.
+ */
+export function railStyle(top: number | string | undefined): CSSProperties {
+  if (top === undefined) return RAIL;
+  const offset = typeof top === "number" ? `${String(top)}px` : top;
+  return { ...RAIL, top, maxHeight: `calc(100dvh - ${offset})` };
+}
+
 /** The results take what is left. `minWidth: 0` so a long word inside a card
  * cannot push the grid wider than its column. */
 const RESULTS_COLUMN: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
@@ -522,6 +541,50 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * rail beside a 110px result column.
    */
   readonly filtersLayout?: SearchFiltersLayout;
+  /**
+   * WHERE the filter rail's sticky top edge is — the offset of whatever chrome
+   * is pinned above this page.
+   *
+   * ```tsx
+   * // the height <PublicShell> publishes, read rather than restated
+   * <SearchPage railTop="var(--stapel-header-height)" />
+   * ```
+   *
+   * The rail is `position: sticky; top: 0` written INLINE, and an inline
+   * declaration is beaten by nothing but `!important` — so a host with a fixed
+   * header had exactly one way to say "start below it", and the fleet's
+   * storefront carried that `!important` as the only one in the repo aimed at a
+   * pair's own geometry. Every deployment with a pinned header has this
+   * problem; none of them could state it.
+   *
+   * A number is pixels; a string is taken as written (a `var()`, a `calc()`,
+   * `"4rem"`). The internal scroll cap moves with it — see {@link railStyle} —
+   * so the rail still ends at the foot of the window rather than that far past
+   * it. Default `0`, which is where the rail has always started.
+   *
+   * The phone SHEET is unaffected: it is a dialog, not a column, and it has no
+   * header to clear.
+   */
+  readonly railTop?: number | string;
+  /**
+   * PIN the results toolbar under whatever chrome is above this page — the
+   * other column's half of {@link railTop}.
+   *
+   * ```tsx
+   * <SearchPage
+   *   railTop="var(--stapel-header-height)"
+   *   stickyToolbar={{ top: "var(--stapel-header-height)" }}
+   * />
+   * ```
+   *
+   * Handed straight to `<SearchResultsPane stickyToolbar>`, which pins the row
+   * it actually drew — the whole header block in the wide shape, the toolbar
+   * alone in the compact one. There is exactly one sort control on a results
+   * page and this pins it where it stands; a host that draws a bar of its own
+   * over the page ends up with two, and the one a person presses is whichever
+   * the layout put under their thumb.
+   */
+  readonly stickyToolbar?: SearchToolbarPin;
   /**
    * 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
@@ -639,6 +702,8 @@ interface SearchPageBodyProps {
   readonly degradationNotice?: DegradationNoticeVariant;
   readonly railFrom?: SearchRailFrom;
   readonly filtersLayout?: SearchFiltersLayout;
+  readonly railTop?: number | string;
+  readonly stickyToolbar?: SearchToolbarPin;
   readonly defaultFiltersOpen?: boolean;
   readonly pageSize?: boolean;
   readonly breadcrumb?: ReactNode;
@@ -838,6 +903,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       toolbar={toolbar}
       {...(props.resultsLead !== undefined ? { lead: props.resultsLead } : {})}
       {...(phoneToolbar ? { header: "compact" as const } : {})}
+      {...(props.stickyToolbar !== undefined
+        ? { stickyToolbar: props.stickyToolbar }
+        : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
       {...(props.wrapResults !== undefined ? { wrapResults: props.wrapResults } : {})}
@@ -998,7 +1066,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         </>
       ) : showFilters ? (
         <Flex align="flex-start" gap={spacing[5]} data-testid="search-page-columns">
-          <div className={RAIL_CLASS} style={RAIL}>
+          <div className={RAIL_CLASS} style={railStyle(props.railTop)}>
             {/* The rail's scrollbar, in the gutter and in the token palette —
                 see `railScrollbarCss`. Hoisted, deduped by `href`. */}
             <style href={RAIL_STYLE_HREF} precedence="default">
@@ -1050,6 +1118,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     degradationNotice,
     railFrom,
     filtersLayout,
+    railTop,
+    stickyToolbar,
     defaultFiltersOpen,
     pageSize,
     breadcrumb,
@@ -1102,6 +1172,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(degradationNotice !== undefined ? { degradationNotice } : {})}
           {...(railFrom !== undefined ? { railFrom } : {})}
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}
+          {...(railTop !== undefined ? { railTop } : {})}
+          {...(stickyToolbar !== undefined ? { stickyToolbar } : {})}
           {...(defaultFiltersOpen !== undefined ? { defaultFiltersOpen } : {})}
           {...(pageSize !== undefined ? { pageSize } : {})}
           {...(breadcrumb !== undefined ? { breadcrumb } : {})}

package/src/default/SearchResultsPane.tsx

@@ -35,7 +35,7 @@ import {
   SkinTheme,
   visuallyHidden,
 } from "@stapel/tokens-antd/skin";
-import { breakpoints, spacing } from "@stapel/tokens";
+import { breakpoints, cssVar, spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import type { SearchItem } from "../api/types.js";
 import { SearchResults } from "../headless/SearchResults.js";
@@ -109,6 +109,101 @@ export type SearchResultsWrapper = (
  */
 export const RESULTS_MAX_WIDTH = 1400;
 
+/**
+ * The class on the row that carries the results toolbar — the sort control, the
+ * view switch, the page size, the count and the surface's own action.
+ *
+ * The row had no element of its own: no class, no `data-testid`, and in the
+ * compact header it was one child of a 112px vertical stack. A host that wanted
+ * it pinned under a fixed header therefore had to reach it with a `:has()` on
+ * the heading beside it, a `display: contents` to drop the stack's box, and the
+ * pane's own breakpoint restated in a media query — three rules aimed at a
+ * shape the pane could change under them at any release.
+ *
+ * It is the same class in BOTH header shapes, and in both it names the row that
+ * would pin: the WIDE header block (heading, count and toolbar on one line —
+ * the block IS the row) and, in `header="compact"`, the toolbar alone, because
+ * pinning the compact stack would put ~112px of chrome under a 56px header on a
+ * 390px screen.
+ */
+export const RESULTS_TOOLBAR_CLASS = "stapel-search-results-toolbar";
+
+/**
+ * Where {@link SearchResultsPaneProps.stickyToolbar} pins the row.
+ *
+ * `top` is a CSS length — a number is pixels, a string is taken as written, so
+ * `top: "var(--stapel-header-height)"` reads the height `<PublicShell>`
+ * publishes rather than restating it. Default `0`.
+ */
+export interface SearchToolbarPin {
+  readonly top?: number | string;
+}
+
+/**
+ * The controls' own line: it may not become two.
+ *
+ * A wrapping row changes height when the count lands — the count arrives with
+ * the answer, one render after the toolbar was already on screen — and a bar
+ * that grows while it is pinned pushes the first cards of the feed down under
+ * the reader's eye. `nowrap` makes the height a constant; `min-inline-size: 0`
+ * plus `overflow-x: auto` is what a row that cannot wrap does with the overflow
+ * instead, which on a phone is the scroll strip every sort row already is.
+ */
+const TOOLBAR_ROW: CSSProperties = {
+  flexWrap: "nowrap",
+  minInlineSize: 0,
+  overflowX: "auto",
+  // Thin, and only when there is something to scroll to — the same reason the
+  // filter rail states its own: an invisible scroll port is indistinguishable
+  // from a row that ends where it was cut.
+  scrollbarWidth: "thin",
+};
+
+/**
+ * The compact header's stack, WITHOUT its box.
+ *
+ * `position: sticky` travels inside its parent, so a toolbar nested in a 112px
+ * stack can move 112px and no further — the parent has to be the results
+ * column, which is as tall as the feed. `display: contents` drops the stack's
+ * box and hands its three rows straight to that column, which is the same
+ * device the fleet's storefront was writing in its own sheet.
+ *
+ * The one visible consequence: the gap between heading, toolbar and count
+ * becomes the column's rather than the stack's.
+ */
+const COMPACT_STACK: CSSProperties = { display: "contents" };
+
+/** The compact shape's toolbar box — the row the pin acts on. */
+const COMPACT_TOOLBAR: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  ...TOOLBAR_ROW,
+};
+
+/**
+ * The pin itself, and it is NET-ZERO in flow: `position` and a layer and a
+ * background, and not one pixel of padding.
+ *
+ * A pinned bar that grows padding to breathe over the cards passing under it
+ * has to take the same padding back as negative margin or the column pays for
+ * it, and the pair does not know which of those two a host's spacing wants. A
+ * row that occupies exactly the box it already occupied cannot shift anything.
+ */
+function toolbarPinStyle(pin: SearchToolbarPin | undefined): CSSProperties | undefined {
+  if (pin === undefined) return undefined;
+  return {
+    position: "sticky",
+    top: pin.top ?? 0,
+    // Over the cards, under the page's own chrome — and under antd's popups,
+    // so the sort select still opens over its own bar.
+    zIndex: 1,
+    // Opaque, or the cards scroll THROUGH the bar. The theme's own surface
+    // role, resolved at paint time, so it follows the brand and the dark side
+    // without a second colour being written here.
+    background: cssVar("surface"),
+  };
+}
+
 /**
  * The results grid. `auto-fill` + `minmax(260px, 1fr)`: as many columns as fit,
  * each at least a readable card and never wider than its share — and the same
@@ -396,6 +491,33 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * viewport is not spent saying "Results" over a list of results.
    */
   readonly header?: "banner" | "compact";
+  /**
+   * PIN the toolbar row under whatever chrome is above this pane.
+   *
+   * ```tsx
+   * // the height <PublicShell> publishes, read rather than restated
+   * <SearchResultsPane stickyToolbar={{ top: "var(--stapel-header-height)" }} />
+   * ```
+   *
+   * A catalogue page is thirty cards long and the control that reorders them is
+   * at the top of it, so by the fourth row the sort is a screenful above the
+   * list it sorts — the same argument that made the filter rail sticky, applied
+   * to the other column.
+   *
+   * It pins the row the pane ACTUALLY DREW, which is why this is a prop and not
+   * a host's stylesheet: the pane knows which of its two header shapes it is in
+   * and a sheet has to guess. In `"banner"` the whole header block pins (it is
+   * one line: heading, count, toolbar). In `"compact"` the toolbar alone pins —
+   * one row, the height of one phone control — because the stack it sits in is
+   * ~112px and that is not a bar anybody can pin under a 56px header.
+   *
+   * Two things it does NOT do, both deliberate: it adds no padding (see
+   * {@link toolbarPinStyle} — a pinned bar that grows to breathe has to give
+   * the room back, and which spacing that is belongs to the host), and it draws
+   * no second sort control. There is exactly one on a results page, and this
+   * pins it where it stands.
+   */
+  readonly stickyToolbar?: SearchToolbarPin;
   /**
    * The category's feature schema, used ONLY to name an applied filter in the
    * empty state's exits ("Without Brand" rather than "Without vendor").
@@ -503,6 +625,7 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
   // The compact arm's caption: the host's word is drawn, the pair's own is
   // not, and `headingVisible` overrides either way — see that prop.
   const compactHeadingSeen = props.headingVisible ?? props.heading !== undefined;
+  const toolbarPin = toolbarPinStyle(props.stickyToolbar);
   const columnRules =
     props.columns === undefined || props.layout === "list"
       ? null
@@ -542,7 +665,15 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
               <div data-testid="search-results-lead">{props.lead}</div>
             )}
             {props.header === "compact" ? (
-              <Flex vertical gap={spacing[2]} data-testid="search-results-header-compact">
+              /* No box of its own — see `COMPACT_STACK`. The three rows are
+                 items of the results COLUMN, so the toolbar between them has a
+                 parent as tall as the feed to travel in. */
+              <Flex
+                vertical
+                gap={spacing[2]}
+                style={COMPACT_STACK}
+                data-testid="search-results-header-compact"
+              >
                 <Typography.Title
                   level={props.headingLevel ?? 4}
                   style={compactHeadingSeen ? { margin: 0 } : visuallyHidden}
@@ -551,19 +682,35 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                 >
                   {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
                 </Typography.Title>
-                {props.toolbar}
+                <div
+                  className={RESULTS_TOOLBAR_CLASS}
+                  data-testid="search-results-toolbar"
+                  style={{ ...COMPACT_TOOLBAR, ...toolbarPin }}
+                >
+                  {props.toolbar}
+                </div>
                 <Count bag={bag} />
               </Flex>
             ) : (
-              <Flex justify="space-between" align="center" wrap gap={spacing[2]}>
+              /* The wide shape's header block IS the toolbar row: one line,
+                 heading at one end, count and controls at the other, and a
+                 direct child of the results column — so it pins as it stands. */
+              <Flex
+                justify="space-between"
+                align="center"
+                gap={spacing[2]}
+                className={RESULTS_TOOLBAR_CLASS}
+                data-testid="search-results-toolbar"
+                {...(toolbarPin !== undefined ? { style: toolbarPin } : {})}
+              >
                 <Typography.Title
                   level={props.headingLevel ?? 4}
-                  style={{ margin: 0 }}
+                  style={{ margin: 0, minInlineSize: 0 }}
                   data-testid="search-results-heading"
                 >
                   {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
                 </Typography.Title>
-                <Flex align="center" wrap gap={spacing[3]}>
+                <Flex align="center" gap={spacing[3]} style={TOOLBAR_ROW}>
                   <Count bag={bag} />
                   {props.toolbar}
                 </Flex>

package/src/default/index.ts

@@ -45,6 +45,7 @@ export {
   RAIL_CLASS,
   RAIL_STYLE_HREF,
   railScrollbarCss,
+  railStyle,
 } from "./SearchPage.js";
 export type {
   SearchPageProps,
@@ -73,6 +74,7 @@ export {
   RESULTS_AUTO_FILL_COLUMNS,
   RESULTS_COLUMNS_CLASS,
   RESULTS_COLUMNS_STYLE_HREF,
+  RESULTS_TOOLBAR_CLASS,
   resultsColumnsCss,
 } from "./SearchResultsPane.js";
 export type {
@@ -80,6 +82,7 @@ export type {
   SearchResultsPaneProps,
   SearchResultsRenderer,
   SearchResultsWrapper,
+  SearchToolbarPin,
 } from "./SearchResultsPane.js";
 
 export {