@stapel/search-react 0.33.0 → 0.34.0

package/src/default/SearchResultsPane.tsx

@@ -120,11 +120,11 @@ export const RESULTS_MAX_WIDTH = 1400;
  * 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.
+ * It is the same class in BOTH header shapes, and in both it names THE SAME
+ * THING: the controls' own line, and never the heading beside it (D452). The
+ * compact shape always drew it that way; the wide shape did not, and pinning a
+ * block that carried the `<h1>` pinned 100px of chrome at 1440 and 150px at
+ * 1280 — see `WIDE_HEADING_ROW`.
  */
 export const RESULTS_TOOLBAR_CLASS = "stapel-search-results-toolbar";
 
@@ -173,6 +173,49 @@ const TOOLBAR_ROW: CSSProperties = {
  */
 const COMPACT_STACK: CSSProperties = { display: "contents" };
 
+/**
+ * The WIDE shape's heading row — a row of its own, at the results column's
+ * full measure (D452).
+ *
+ * The heading used to be the leading flex item of the block that pins, with
+ * the controls as the trailing one. Two things followed, and both were
+ * measured on the stand:
+ *
+ *  - the controls row is `nowrap` and holds a count, a sort select, a page
+ *    size and a view switch, so it took whatever width it needed and left the
+ *    heading **415px** of a 1200px column. An `<h1>` at 42px (50 at 1280) then
+ *    wrapped to TWO LINES;
+ *  - those two lines were inside the pinned box, so what stood under the
+ *    header while the feed scrolled was **100px** of chrome at 1440 and
+ *    **150px** at 1280 — a third of the fold on a laptop.
+ *
+ * Nothing about the heading belongs in a pinned bar: it names the page once,
+ * it is read once, and it is the one element on the page whose length the pair
+ * does not control (`resultsHeading` is the host's sentence — "Buy a
+ * Samsung Galaxy S23 in Kazan"). So it takes its own line at the full width,
+ * where it has room not to wrap, and the pin acts on the controls alone —
+ * which is what `header="compact"` already did.
+ *
+ * `100%` is DECLARED rather than left to the column's `align-items: stretch`:
+ * the row is what a host reads to know the heading is not in the pinned box,
+ * and a width that only happens to be full is not a contract.
+ */
+const WIDE_HEADING_ROW: CSSProperties = { inlineSize: "100%", minInlineSize: 0 };
+
+/** The wide heading itself: no margin of its own — the column's gap is the
+ * rhythm — and free to shrink inside its row rather than forcing it wider. */
+const WIDE_HEADING: CSSProperties = { margin: 0, minInlineSize: 0 };
+
+/**
+ * The wide row's trailing group — the surface's controls.
+ *
+ * `flex: 0 0 auto`: the count on the leading end is the elastic half (it is
+ * one short string and it arrives late), and the controls keep every pixel
+ * they need. Both ends shrinking is how a sort select ends up narrower than
+ * its own longest option.
+ */
+const TOOLBAR_END: CSSProperties = { flex: "0 0 auto" };
+
 /** The compact shape's toolbar box — the row the pin acts on. */
 const COMPACT_TOOLBAR: CSSProperties = {
   display: "flex",
@@ -692,29 +735,35 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                 <Count bag={bag} />
               </Flex>
             ) : (
-              /* 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, minInlineSize: 0 }}
-                  data-testid="search-results-heading"
+              /* D452 — the heading is its OWN row, at the column's full width,
+                 and the row that pins is the controls. See `WIDE_HEADING_ROW`.
+                 Both are direct children of the results column: the toolbar
+                 has a parent as tall as the feed to travel in, and the heading
+                 has the whole measure to set its line in. */
+              <>
+                <div style={WIDE_HEADING_ROW} data-testid="search-results-heading-row">
+                  <Typography.Title
+                    level={props.headingLevel ?? 4}
+                    style={WIDE_HEADING}
+                    data-testid="search-results-heading"
+                  >
+                    {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
+                  </Typography.Title>
+                </div>
+                <Flex
+                  justify="space-between"
+                  align="center"
+                  gap={spacing[3]}
+                  className={RESULTS_TOOLBAR_CLASS}
+                  data-testid="search-results-toolbar"
+                  style={{ ...TOOLBAR_ROW, ...toolbarPin }}
                 >
-                  {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
-                </Typography.Title>
-                <Flex align="center" gap={spacing[3]} style={TOOLBAR_ROW}>
                   <Count bag={bag} />
-                  {props.toolbar}
+                  <Flex align="center" gap={spacing[3]} style={TOOLBAR_END}>
+                    {props.toolbar}
+                  </Flex>
                 </Flex>
-              </Flex>
+              </>
             )}
 
             <DegradationNotice

package/src/headless/FacetPanel.tsx

@@ -29,6 +29,17 @@ export interface FacetPanelBag {
    * category) — it is NOT what a failed query looks like.
    */
   readonly state: LoadState<readonly FacetGroup[]>;
+  /**
+   * The groups in hand belong to the PREVIOUS answer, and a newer one is in
+   * flight — `LoadReady.refreshing`, lifted out of the state so a skin can
+   * read it without narrowing the union first.
+   *
+   * A skin holds its geometry still while this is `true`: the axes are about
+   * to change, and a rail that resizes group by group as they arrive is the
+   * 0.0586 CLS a partition press measured (p43). It is never `true` on a
+   * first load — there is nothing to hold still then.
+   */
+  readonly refreshing: boolean;
   /**
    * `true` when the counts came from a SAMPLE because the candidate set
    * exceeded the backend's cap. The panel must say so — the spec makes this
@@ -228,7 +239,23 @@ export function useFacetPanel(props: {
     props.enabled !== undefined ? { enabled: props.enabled } : undefined
   );
 
-  const envelope = loadStateFromQuery(query);
+  /*
+   * KEEP THE PREVIOUS ANSWER, AND SAY SO (p43, CLS 0.0586 on a partition press).
+   *
+   * `useSearchQuery` already runs with `placeholderData: keepPreviousData`, so
+   * the data in hand during a key change is the previous answer's — the panel
+   * has been drawing it for three releases. What it could not do is TELL a skin
+   * that this is what it was doing, so the rail resized group by group as the
+   * new axis's facets landed: `facet-group-make` and `facet-group-model` moved
+   * their neighbours as their option counts changed under them.
+   *
+   * `keepPrevious` reads TanStack's own `isPlaceholderData` into
+   * `LoadReady.refreshing`, which every projection below carries across
+   * (`mapLoad`, and `useHostFacetLabels` through it). It is set on EVERY ready
+   * answer once asked for, `false` included, so a skin keying its DOM off it
+   * does not grow and drop a wrapper as the flag comes and goes.
+   */
+  const envelope = loadStateFromQuery(query, { keepPrevious: true });
   const meta = envelope.status === "ready" ? envelope.data.facet_meta : EMPTY_META;
 
   const groups = mapLoad(envelope, (data) =>
@@ -271,6 +298,9 @@ export function useFacetPanel(props: {
 
   return {
     state: labelled,
+    // Read off the ANSWER's own state rather than off the projection, so a
+    // label pass that returns the groups untouched cannot lose it.
+    refreshing: envelope.status === "ready" && envelope.refreshing === true,
     approximate: meta.approximate,
     skipped: meta.skipped,
     counted: meta.counted,