@stapel/search-react 0.35.0 → 0.36.1

package/src/default/SearchPage.tsx

@@ -80,6 +80,7 @@ import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { FacetPanelPane } from "./FacetPanelPane.js";
 import type {
   CategoryFilterSlotProps,
+  FacetPanelPaneProps,
   GeoFilterSlotProps,
 } from "./FacetPanelPane.js";
 import { FilterChips } from "./FilterChips.js";
@@ -107,6 +108,54 @@ import type { ThemeModeProp } from "./types.js";
 /** Where the filters live: beside the results, or behind a button in a sheet. */
 export type SearchFiltersLayout = "column" | "sheet";
 
+/**
+ * WHY the filter sheet's open state moved — handed to `onFiltersOpenChange`
+ * beside the new value.
+ *
+ * A host that only mirrors the boolean can ignore it. A host that ACTS on the
+ * close cannot: "the person pressed Show results" and "the person swiped the
+ * sheet away" are the same `false` and not the same event, and a container
+ * that logs one as the other reports an intent nobody had.
+ *
+ *  - `open` — the sheet was asked for (the all-filters chip, the location
+ *    row's door).
+ *  - `apply` — the footer's "Show N results" committed and closed it.
+ *  - `dismiss` — the dialog itself closed: the X, the scrim, Escape.
+ *  - `consumer` — the host closed it through `filtersHeader`'s `closeFilters`.
+ */
+export type SearchFiltersOpenReason = "open" | "apply" | "dismiss" | "consumer";
+
+/** What `filtersHeader` is handed when a host passes a function. */
+export interface SearchFiltersHeaderSlotProps {
+  /**
+   * Shut the sheet, with the reason `"consumer"`.
+   *
+   * This is the whole point of the callback form: a control in this slot that
+   * NAVIGATES on a press (a partition or axis chip that changes the route)
+   * has to close the sheet on that same press, or the next page opens under a
+   * drawer that is still up. Without it a host had to lift the open state out
+   * of the page — which it could not, because the page only offered
+   * `defaultFiltersOpen`.
+   *
+   * Harmless in the column layout, where there is no sheet to shut: the page
+   * still reports the change, and nothing moves on screen.
+   */
+  readonly closeFilters: () => void;
+  /** Is the sheet open around this header right now. */
+  readonly open: boolean;
+}
+
+/**
+ * The `filtersHeader` slot: a node, or a function told the sheet's state.
+ *
+ * The node form is what it has always been. The function form exists so a
+ * header can close the sheet it is inside without the host owning the open
+ * state — see {@link SearchFiltersHeaderSlotProps.closeFilters}.
+ */
+export type SearchFiltersHeader =
+  | ReactNode
+  | ((slot: SearchFiltersHeaderSlotProps) => ReactNode);
+
 /**
  * WHERE the filter rail earns its 280px, when the token `tablet` edge is the
  * wrong place to draw it.
@@ -413,6 +462,22 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * saves less than folding a column's does. Set it to override either.
    */
   readonly visibleGroups?: number | null;
+  /**
+   * The filter panel's footer — what the filters DID (the live count) and the
+   * way out of them — see {@link FacetPanelPaneProps.footerBar}.
+   *
+   * Defaulted PER LAYOUT: `"static"` in the desktop COLUMN (the rail scrolls
+   * with the page, and a bar pinned to the port's floor sat on top of the last
+   * groups), and none in the phone SHEET, whose own "Show N results" footer is
+   * already the count AND the exit.
+   *
+   * It is a PROP because it could not be reached any other way: the bar writes
+   * its own `display` inline, so a host stylesheet cannot suppress it without
+   * `!important`, and this page hard-coded the column's value. A surface that
+   * draws its own count under the rail passes `false`; one that wants the bar
+   * inside the sheet as well passes `"sticky"`.
+   */
+  readonly footerBar?: FacetPanelPaneProps["footerBar"];
   /** Print the engine's list of uncounted facet slugs in the filter panel.
    * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
   readonly skippedNotice?: boolean;
@@ -437,8 +502,12 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * for. Whatever a host renders here reads and writes the same URL state as
    * the facets beside it (`useSearchState()`), so it is a filter in every
    * sense that matters and not a decoration bolted on top.
+   *
+   * A FUNCTION is handed `{ closeFilters, open }` — for a header whose own
+   * control navigates away, which on a phone has to take the sheet down with
+   * it. See {@link SearchFiltersHeaderSlotProps}.
    */
-  readonly filtersHeader?: ReactNode;
+  readonly filtersHeader?: SearchFiltersHeader;
   /**
    * The block-size that slot will END UP at, declared before it has anything
    * in it — a number in CSS pixels or any length (`"96px"`, `"6rem"`).
@@ -624,9 +693,47 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * from a category page), and for the story that photographs the sheet —
    * a state reached only by a tap is a state nothing outside a browser has
    * ever seen. The person still closes it; this is the initial value, not a
-   * controlled one.
+   * controlled one — pass `filtersOpen` for that.
    */
   readonly defaultFiltersOpen?: boolean;
+  /**
+   * The sheet's open state, OWNED BY THE HOST.
+   *
+   * React's usual contract: pass this and the page stops keeping its own copy
+   * — every open and every close is a call to `onFiltersOpenChange` and
+   * nothing moves until the value comes back. Leave it out and the page is
+   * uncontrolled exactly as before, `defaultFiltersOpen` its initial value.
+   *
+   * It exists because a control the host renders INSIDE the sheet can end the
+   * search that sheet belongs to. A partition chip in `filtersHeader` that
+   * navigates leaves the drawer standing over the page it opened, and the
+   * host had no handle on the state to shut it — the page exposed the initial
+   * value and nothing else. A host that only needs the close and not the
+   * state can take `filtersHeader`'s `closeFilters` instead and keep the page
+   * uncontrolled.
+   *
+   * ```tsx
+   * const [filtersOpen, setFiltersOpen] = useState(false);
+   * <SearchPage
+   *   filtersOpen={filtersOpen}
+   *   onFiltersOpenChange={(open) => { setFiltersOpen(open); }}
+   *   filtersHeader={<PartitionChips onPick={(href) => { setFiltersOpen(false); navigate(href); }} />}
+   * />
+   * ```
+   */
+  readonly filtersOpen?: boolean;
+  /**
+   * Told that the sheet wants to open or close, and WHY — see
+   * {@link SearchFiltersOpenReason}.
+   *
+   * Called in both modes, controlled and not: a host that wants to watch the
+   * sheet (an analytics event on the dismiss, a scroll lock of its own) does
+   * not have to take ownership of the state to hear about it.
+   */
+  readonly onFiltersOpenChange?: (
+    open: boolean,
+    reason: SearchFiltersOpenReason
+  ) => void;
   /** Offer a page-size control beside the sort. Default `true`. */
   readonly pageSize?: boolean;
   /**
@@ -702,6 +809,7 @@ interface SearchPageBodyProps {
   readonly resultsLead?: ReactNode;
   readonly dictionaryMode?: "field" | "inline" | "sheet";
   readonly visibleGroups?: number | null;
+  readonly footerBar?: FacetPanelPaneProps["footerBar"];
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly categoryFeaturesPending?: boolean;
   readonly filtersHeaderReserve?: number | string;
@@ -717,7 +825,7 @@ interface SearchPageBodyProps {
   readonly geoLabel?: ReactNode;
   readonly skippedNotice?: boolean;
   readonly footer?: ReactNode;
-  readonly filtersHeader?: ReactNode;
+  readonly filtersHeader?: SearchFiltersHeader;
   readonly resultsHeader?: ReactNode;
   readonly appliedChips?: boolean | "desktop";
   readonly otherCategories?: boolean;
@@ -731,6 +839,11 @@ interface SearchPageBodyProps {
   readonly railTop?: number | string;
   readonly stickyToolbar?: SearchToolbarPin;
   readonly defaultFiltersOpen?: boolean;
+  readonly filtersOpen?: boolean;
+  readonly onFiltersOpenChange?: (
+    open: boolean,
+    reason: SearchFiltersOpenReason
+  ) => void;
   readonly pageSize?: boolean;
   readonly breadcrumb?: ReactNode;
   readonly wrapResults?: SearchResultsWrapper;
@@ -767,7 +880,36 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       : surface === "sheet"
         ? "sheet"
         : "column");
-  const [sheetOpen, setSheetOpen] = useState(props.defaultFiltersOpen === true);
+  /**
+   * The rail's footer bar, defaulted PER LAYOUT and overridable — see
+   * {@link SearchPageProps.footerBar}.
+   *
+   * STATIC, not sticky, in the column: the rail scrolls with the page, and a
+   * bar pinned to the port's floor sat on top of the last groups. None in the
+   * sheet, whose own "Show N results" footer is already the count and the exit.
+   */
+  const footerBar: FacetPanelPaneProps["footerBar"] =
+    props.footerBar ?? (layout === "sheet" ? undefined : "static");
+  // Controlled or not, decided by the PRESENCE of `filtersOpen` and read once
+  // per render — the state the page keeps is only ever the uncontrolled half,
+  // and a controlled host's value is never copied into it (copying it is how
+  // a controlled component starts disagreeing with its owner one frame after
+  // the owner refuses a change).
+  const controlledFiltersOpen = props.filtersOpen;
+  const [ownFiltersOpen, setOwnFiltersOpen] = useState(
+    props.defaultFiltersOpen === true
+  );
+  const sheetOpen = controlledFiltersOpen ?? ownFiltersOpen;
+  const { onFiltersOpenChange } = props;
+  const setSheetOpen = (next: boolean, reason: SearchFiltersOpenReason): void => {
+    if (controlledFiltersOpen === undefined) {
+      setOwnFiltersOpen(next);
+    }
+    onFiltersOpenChange?.(next, reason);
+  };
+  const closeFilters = (): void => {
+    setSheetOpen(false, "consumer");
+  };
 
   // How the results are ARRANGED. Component state, not URL state: it changes
   // how the same answer is drawn, never what the answer is, so it must not
@@ -857,7 +999,14 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             ? { style: { minBlockSize: props.filtersHeaderReserve } }
             : {})}
         >
-          {filtersHeader}
+          {/* The function form is called HERE, inside the slot it fills, so a
+              header that reads `open` re-renders with the sheet. Presence is
+              still decided by the PROP above and never by what the function
+              returned: a header that renders nothing this frame must not
+              collapse the box it reserved. */}
+          {typeof filtersHeader === "function"
+            ? filtersHeader({ closeFilters, open: sheetOpen })
+            : filtersHeader}
         </div>
       )}
       {/* The facet panel is skipped entirely when the only thing it would draw
@@ -873,11 +1022,8 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           result count scrolled out of sight above the fold. */}
       {filtersEmpty ? null : (
         <FacetPanelPane
-          {...(layout === "sheet"
-            ? { heading: null }
-            : // STATIC, not sticky: the rail scrolls with the page, and a bar
-              // pinned to the port's floor sat on top of the last groups.
-              { footerBar: "static" as const })}
+          {...(layout === "sheet" ? { heading: null } : {})}
+          {...(footerBar !== undefined ? { footerBar } : {})}
           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
@@ -1036,7 +1182,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           // has the whole panel on screen beside this row.
           filtersDoor={layout === "sheet"}
           onOpenAll={() => {
-            setSheetOpen(true);
+            setSheetOpen(true, "open");
           }}
         />
       )}
@@ -1073,7 +1219,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
               still the whole panel, for the person who wants all of it. */}
           <FilterChips
             onOpenAll={() => {
-              setSheetOpen(true);
+              setSheetOpen(true, "open");
             }}
             {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
             {...(locale !== undefined ? { locale } : {})}
@@ -1092,7 +1238,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           <SkinDialog
             open={sheetOpen}
             onClose={() => {
-              setSheetOpen(false);
+              setSheetOpen(false, "dismiss");
             }}
             title={t(SEARCH_I18N_KEYS.facetsTitle)}
             dismissLabel={t(SEARCH_I18N_KEYS.filtersDismiss)}
@@ -1105,7 +1251,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
                 data-analytics="none"
                 data-analytics-reason="the filters are already applied; this closes the sheet"
                 onClick={() => {
-                  setSheetOpen(false);
+                  setSheetOpen(false, "apply");
                 }}
               >
                 {applyLabel}
@@ -1175,6 +1321,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     railTop,
     stickyToolbar,
     defaultFiltersOpen,
+    filtersOpen,
+    onFiltersOpenChange,
     pageSize,
     breadcrumb,
     wrapResults,
@@ -1187,6 +1335,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     resultsHeadingVisible,
     dictionaryMode,
     visibleGroups,
+    footerBar,
     pinnedFacets,
     mode,
     ...parseOptions
@@ -1201,6 +1350,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(resultsHeadingVisible !== undefined ? { resultsHeadingVisible } : {})}
           {...(dictionaryMode !== undefined ? { dictionaryMode } : {})}
           {...(visibleGroups !== undefined ? { visibleGroups } : {})}
+          {...(footerBar !== undefined ? { footerBar } : {})}
           {...(pinnedFacets !== undefined ? { pinnedFacets } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(categoryFeaturesPending !== undefined
@@ -1233,6 +1383,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(railTop !== undefined ? { railTop } : {})}
           {...(stickyToolbar !== undefined ? { stickyToolbar } : {})}
           {...(defaultFiltersOpen !== undefined ? { defaultFiltersOpen } : {})}
+          {...(filtersOpen !== undefined ? { filtersOpen } : {})}
+          {...(onFiltersOpenChange !== undefined ? { onFiltersOpenChange } : {})}
           {...(pageSize !== undefined ? { pageSize } : {})}
           {...(breadcrumb !== undefined ? { breadcrumb } : {})}
           {...(wrapResults !== undefined ? { wrapResults } : {})}

package/src/default/SearchResultsPane.tsx

@@ -216,6 +216,24 @@ const WIDE_HEADING: CSSProperties = { margin: 0, minInlineSize: 0 };
  */
 const TOOLBAR_END: CSSProperties = { flex: "0 0 auto" };
 
+/**
+ * The wide row's LEADING half, and it is always in the row (D466).
+ *
+ * The count arrives with the answer, one render after the toolbar is already
+ * on screen, and `<Count>` renders nothing at all until it does — so a row
+ * spaced by `justify: space-between` had ONE item in the first frame and TWO
+ * in the second, which moved the sort/view control from the leading edge to
+ * the trailing one as the number landed: x 328→459 at 1280, 564→863 at 1920,
+ * 312→796 at 1100, and the same jump on a seller's page.
+ *
+ * A leading box that is always there, and grows, is what fixes it: the
+ * trailing group's x is then `row right − its own width` in every frame,
+ * whatever the count says or whether it says anything. `min-inline-size: 0`
+ * lets a long count shrink into the space that is left rather than push the
+ * controls, which the row's own `overflow-x` then scrolls.
+ */
+const TOOLBAR_LEAD: CSSProperties = { flex: "1 1 auto", minInlineSize: 0 };
+
 /** The compact shape's toolbar box — the row the pin acts on. */
 const COMPACT_TOOLBAR: CSSProperties = {
   display: "flex",
@@ -751,14 +769,19 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                   </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 }}
                 >
-                  <Count bag={bag} />
+                  {/* The elastic half, present whether or not there is a
+                      count in it — see TOOLBAR_LEAD. It is what holds the
+                      controls against the trailing edge in the frame before
+                      the number arrives, so nothing travels when it does. */}
+                  <div style={TOOLBAR_LEAD} data-testid="search-results-toolbar-lead">
+                    <Count bag={bag} />
+                  </div>
                   <Flex align="center" gap={spacing[3]} style={TOOLBAR_END}>
                     {props.toolbar}
                   </Flex>

package/src/default/index.ts

@@ -50,6 +50,9 @@ export {
 export type {
   SearchPageProps,
   SearchFiltersLayout,
+  SearchFiltersHeader,
+  SearchFiltersHeaderSlotProps,
+  SearchFiltersOpenReason,
   SearchRailFrom,
 } from "./SearchPage.js";