@stapel/search-react 0.34.0 → 0.36.0

package/src/default/FacetGroupControl.tsx

@@ -997,6 +997,81 @@ export interface FacetGroupControlProps {
   readonly refreshing?: boolean;
 }
 
+/* ── THE DECLARED BOX (p41) ───────────────────────────────────────────────
+ *
+ * What a group's box is worth BEFORE anything has been measured. Four stated
+ * numbers, deliberately a shade UNDER what the skin draws: the reservation is
+ * a `min-block-size` floor, so a number below the real one is a no-op the
+ * moment content exists, while a number above it is a hole nothing fills.
+ *
+ * They exist because the p43 reserve — the height a group was last measured at
+ * — is only available from the SECOND answer onwards (`FacetPanelBag.
+ * refreshing` is never true on a first load), and the first mount is precisely
+ * the pass with nothing to stand on: the group renders at content height, and
+ * every fact that lands after it (a label the host's vocabulary resolved, a
+ * count, a dependent axis's options arriving with the next answer) re-lays the
+ * column under the reader's eye.
+ */
+
+/** One option row: antd's checkbox line, without the gap between rows. */
+export const FACET_OPTION_ROW_HEIGHT = 24;
+
+/** One row of `size="small"` pills in a segmented group. */
+export const FACET_PILL_ROW_HEIGHT = 24;
+
+/** How many pills a 280px rail fits across before the row wraps. A stated
+ * estimate — the row is `wrap`, so the true count is a function of the labels
+ * — and it is used only to floor the box, never to cap it. */
+export const FACET_PILLS_PER_ROW = 3;
+
+/** The group's own heading line, and the same for the fold's link button. */
+export const FACET_HEADING_HEIGHT = 22;
+
+/**
+ * The box a group declares for itself — heading, rows, fold — in CSS pixels.
+ *
+ * Stated per SHAPE, because the shapes are not variations of one control: a
+ * dictionary's closed face is one field however many values the vocabulary
+ * holds, a segmented group is a wrapping row of pills, and a checkbox group is
+ * one line per shown option.
+ *
+ * Exported so a host (and this package's own tests) can assert the number the
+ * rail reserves rather than discovering it from a screenshot.
+ */
+export function facetGroupReservedHeight(input: {
+  readonly shape: FacetGroupShape;
+  /** How many option rows are actually drawn — after the fold, not before. */
+  readonly rows: number;
+  /** Is the group's heading drawn at all? */
+  readonly heading: boolean;
+  /** Is the group open? A closed disclosure is its header and nothing else. */
+  readonly open: boolean;
+  /** Is the "Show all (N)" button drawn under the rows? */
+  readonly folded: boolean;
+}): number {
+  const gap = input.shape === "segmented" ? spacing[2] : spacing[1];
+  const parts: number[] = [];
+  if (input.heading) parts.push(FACET_HEADING_HEIGHT);
+  if (input.open) {
+    if (input.shape === "dictionary") {
+      parts.push(controls.height);
+    } else if (input.shape === "segmented") {
+      parts.push(
+        Math.ceil(Math.max(input.rows, 1) / FACET_PILLS_PER_ROW) *
+          FACET_PILL_ROW_HEIGHT
+      );
+    } else {
+      for (let row = 0; row < input.rows; row += 1) {
+        parts.push(FACET_OPTION_ROW_HEIGHT);
+      }
+    }
+    if (input.folded) parts.push(FACET_HEADING_HEIGHT);
+  }
+  if (parts.length === 0) return 0;
+  const gaps = (parts.length - 1) * gap;
+  return parts.reduce((total, part) => total + part, 0) + gaps;
+}
+
 /**
  * Is this group a HEADING WITH NOTHING UNDER IT?
  *
@@ -1044,6 +1119,17 @@ export function FacetGroupControl(
    * render, and the measurement is deliberately not taken while refreshing —
    * a reserved box would otherwise remember its own reservation and the floor
    * could only ever ratchet upwards.
+   *
+   * ── AND THE FIRST MOUNT, WHICH HAD NOTHING (p41) ─────────────────────────
+   *
+   * A measurement is only available from the second answer onwards, so the
+   * paragraph above covers every pass but the one a cold load is made of. Until
+   * a box has been measured the group stands on the box it DECLARES — see
+   * {@link facetGroupReservedHeight} — which is a stated number per shape and
+   * row count rather than whatever the content happened to lay out to. A floor
+   * under the real height is invisible; what it buys is that the box exists at
+   * all in the frames where a label, a count or a dependent axis's options have
+   * not landed yet.
    */
   const boxRef = useRef<HTMLDivElement | null>(null);
   const settledHeight = useRef<number | undefined>(undefined);
@@ -1055,7 +1141,6 @@ export function FacetGroupControl(
     // render): a floor of zero is not a reservation, so nothing is remembered.
     if (node !== null && node.offsetHeight > 0) settledHeight.current = node.offsetHeight;
   });
-  const reserved = refreshing ? settledHeight.current : undefined;
 
   const disclosure = props.collapsible === true && props.heading !== false;
   const open = !disclosure || openState;
@@ -1086,6 +1171,34 @@ export function FacetGroupControl(
       ? nodes.slice(0, Math.min(limit ?? nodes.length, nodes.length - demoted))
       : nodes;
 
+  /* The floor, and where it comes from. The DECLARED box is the rows this
+     group is drawing, so it stands on every render and can never be a hole;
+     the MEASURED one — this box, on this deployment, at this width — is added
+     on top of it while an answer is in flight, and released with the answer.
+     Zero is not a reservation and is never written. */
+  const declared = facetGroupReservedHeight({
+    shape,
+    rows: shown.length,
+    heading: props.heading !== false,
+    open,
+    folded,
+  });
+  const measured = settledHeight.current;
+  /* The declared box stands ALWAYS — it is the rows this group is drawing, so
+     it can never be a hole — and the measured one is added only while an
+     answer is in flight. That is the difference between the two: the
+     declaration is what this group needs, and the measurement is what it
+     happened to occupy a moment ago, which is a floor worth holding exactly as
+     long as the thing that filled it is being replaced. */
+  const reserved =
+    (refreshing ? Math.max(measured ?? 0, declared) : declared) || undefined;
+  const reservedSource =
+    reserved === undefined
+      ? undefined
+      : refreshing && measured !== undefined && measured > declared
+        ? "measured"
+        : "declared";
+
   return (
     <Flex
       ref={boxRef}
@@ -1098,9 +1211,14 @@ export function FacetGroupControl(
       data-counted={group.counted ? "true" : "false"}
       data-shape={shape}
       // The reservation, readable from a stand: `data-reserved` is the height
-      // this group is standing on while the next answer is in flight.
+      // this group is standing on, and `data-reserved-source` says whether the
+      // number was MEASURED on this deployment or DECLARED by the pair — which
+      // is the difference between a refresh and a first mount.
       {...(refreshing ? { "data-refreshing": "true" } : {})}
       {...(reserved !== undefined ? { "data-reserved": String(reserved) } : {})}
+      {...(reservedSource !== undefined
+        ? { "data-reserved-source": reservedSource }
+        : {})}
       // Who named this heading — `none` means the raw slug is on screen
       // because the answer sent no label and the schema defines none. It is
       // drawn (a heading a person cannot read still beats none) and it is

package/src/default/FacetPanelPane.tsx

@@ -84,6 +84,7 @@ import {
   SlotPlaceholder,
   actionAvailable,
   actionBlocked,
+  loadLoading,
   useT,
   useTPlural,
 } from "@stapel/core";
@@ -230,6 +231,31 @@ export interface FacetPanelPaneProps extends ThemeModeProp {
    * slugs get a numeric range row, and of which slugs are a filter at all
    * (`isFacetableFeature`: an `imei` is counted and is not one). */
   readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * The schema is ON ITS WAY — the third state {@link categoryFeatures} does
+   * not have, and the whole of p41.
+   *
+   * `categoryFeatures: undefined` says two different things today: "this
+   * category hangs no schema" and "the read has not answered yet". The panel
+   * cannot tell them apart, so on a page whose schema is a SEPARATE read from
+   * the search (a category leaf: two requests, two arrival times) it draws the
+   * rail the moment the answer lands and then draws it AGAIN, differently, when
+   * the schema arrives — because both the SHAPE of every group
+   * (`facetGroupShape` reads `maxSelected` and `ref_select` off the feature)
+   * and the ORDER of the rail (`orderFacetGroupsBySchema` puts the schema's
+   * required axes first) are functions of it. Measured on a live cars leaf: the
+   * make and the model went from three-row checkbox lists to one-row dictionary
+   * fields, condition and colour from checkboxes to pills, and the order
+   * changed under all of them — 0.0586 CLS on a plain cold load, with
+   * `facet-group-make` moving 152px and `facet-group-model` 76px (p41).
+   *
+   * With `categoryFeaturesPending` the panel keeps the box it already reserves
+   * for a load in flight until the schema has spoken, and draws the rail ONCE,
+   * in the shape and the order it will keep. A host passes its schema query's
+   * own pending flag; the default is `false`, so a surface that never had a
+   * schema to wait for is unchanged.
+   */
+  readonly categoryFeaturesPending?: boolean;
   readonly locale?: string;
   readonly enabled?: boolean;
   /**
@@ -620,6 +646,16 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
           : {})}
       >
         {(bag) => {
+          /* THE ANSWER THIS PANEL DRAWS FROM, AND WHEN IT IS ALLOWED TO (p41).
+             A schema still in flight makes the groups in hand provisional: they
+             would be drawn in one shape and one order now and in another the
+             moment it lands. `loadLoading()` is the honest state for that — the
+             panel already reserves a box for it — and it is the SAME state the
+             pane hands every consumer below, so the ranges arm, the empty arm
+             and the group list cannot disagree about whether there is an answer
+             on screen. See `FacetPanelPaneProps.categoryFeaturesPending`. */
+          const schemaPending = props.categoryFeaturesPending === true;
+          const answer = schemaPending ? loadLoading() : bag.state;
           // Built INSIDE the bag, because which axes exist is a property of
           // the ANSWER now: `facet_meta.core_ranges` names the core columns
           // this server can actually filter on (`r.price`), and the corpus
@@ -748,6 +784,12 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                that dims or freezes the column has one thing to hang it on
                instead of racing the pair's own queries to find out. */
             data-facets-refreshing={bag.refreshing ? "true" : "false"}
+            /* AND WHEN ITS SHAPE IS NOT DECIDED YET (p41). The groups in hand
+               are provisional while the category's schema is in flight, because
+               the schema decides both the shape of every group and the order of
+               the rail. A walker reads this to know why the column is a
+               skeleton with a settled answer behind it. */
+            data-facets-schema={schemaPending ? "pending" : "settled"}
           >
             {/* In a 280px rail this row laid the word "Filters" out in a
                 43x78 box, three lines, one syllable each — see FACET_HEADING.
@@ -836,8 +878,8 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                 the checkboxes on a leaf whose only filter is a price — the one
                 shape where the rail is nothing else. Drawn here, in the place
                 the merged list would have put them. */}
-            {bag.state.status === "ready" &&
-              bag.state.data.length === 0 &&
+            {answer.status === "ready" &&
+              answer.data.length === 0 &&
               ranges.length > 0 && (
               <Flex vertical gap={spacing[3]} data-testid="search-ranges">
                 {ranges.map(rangeRow)}
@@ -864,7 +906,7 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                    many skeleton rows, each `RANGE_ROW_MIN_HEIGHT` tall like
                    the row it will become. */}
             <LoadList
-              state={bag.state}
+              state={answer}
               testId="facets"
               skeletonRows={4}
               loading={

package/src/default/SearchPage.tsx

@@ -107,6 +107,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.
@@ -312,6 +360,14 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
   readonly adapter: SearchParamsAdapter;
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
+  /**
+   * The schema is ON ITS WAY — the third state `categoryFeatures` does not
+   * have. Handed straight to the filter panel, which holds the box it already
+   * reserves rather than drawing a rail it is about to re-shape and re-order.
+   * See {@link FacetPanelPaneProps.categoryFeaturesPending} for what was
+   * measured without it (p41).
+   */
+  readonly categoryFeaturesPending?: boolean;
   readonly locale?: string;
   /**
    * Name the facet values neither the answer nor the category schema names —
@@ -429,8 +485,28 @@ 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"`).
+   *
+   * For the host whose header is a SEPARATE read from the search: a category
+   * page's partition row is two chained catalogue requests behind the answer,
+   * so the rail draws its groups first and the row drops in over them a beat
+   * later, pushing every filter under it down (p41). The band is in flow from
+   * the first frame with this set — an empty box of the right height, then the
+   * control inside it — and the pair never guesses the number, because the
+   * height of a control it does not own is not the pair's to know.
+   *
+   * A FLOOR, like every other reservation here: a header taller than the
+   * declared number still takes the room it needs.
+   */
+  readonly filtersHeaderReserve?: number | string;
   /**
    * The row ABOVE the chips and the results — where `<LocationSummaryLine>`
    * goes on the phone SERP.
@@ -600,9 +676,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;
   /**
@@ -679,6 +793,8 @@ interface SearchPageBodyProps {
   readonly dictionaryMode?: "field" | "inline" | "sheet";
   readonly visibleGroups?: number | null;
   readonly categoryFeatures?: readonly FeatureDef[];
+  readonly categoryFeaturesPending?: boolean;
+  readonly filtersHeaderReserve?: number | string;
   readonly renderEmptyExits?: () => ReactNode;
   readonly locale?: string;
   readonly pinnedFacets?: readonly string[];
@@ -691,7 +807,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;
@@ -705,6 +821,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;
@@ -741,7 +862,26 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       : surface === "sheet"
         ? "sheet"
         : "column");
-  const [sheetOpen, setSheetOpen] = useState(props.defaultFiltersOpen === true);
+  // 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
@@ -787,7 +927,13 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     // have called that column empty.
     ...(facets.ranges !== undefined ? { ranges: facets.ranges } : {}),
   });
+  /* A schema still in flight makes every reading below provisional — see
+     `FacetPanelPaneProps.categoryFeaturesPending`. "Nothing to filter by" in
+     particular: the groups in hand are the ones the panel is about to redraw,
+     and a column closed on them would open again a beat later. */
+  const schemaPending = props.categoryFeaturesPending === true;
   const filtersEmpty =
+    !schemaPending &&
     facets.state.status === "ready" &&
     facets.state.data.length === 0 &&
     // `withheld` (groups the server counted and held back for covering too
@@ -806,11 +952,35 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
         props.renderCategoryFilter === undefined)) &&
     state.lang === undefined &&
     (props.languages ?? []).length === 0;
-  const showFilters = filtersHeader !== undefined || !filtersEmpty;
+  const showFilters =
+    filtersHeader !== undefined ||
+    props.filtersHeaderReserve !== undefined ||
+    !filtersEmpty;
 
   const panel = (
     <Flex vertical gap={spacing[4]}>
-      {filtersHeader}
+      {/* THE HOST'S BAND, IN FLOW FROM THE FIRST FRAME (p41). The wrapper is
+          drawn whenever there is something to draw OR a height to hold, so a
+          header that arrives with a second read lands INTO its box rather than
+          inserting one above the groups. See `filtersHeaderReserve`. */}
+      {(filtersHeader !== undefined ||
+        props.filtersHeaderReserve !== undefined) && (
+        <div
+          data-testid="search-filters-header"
+          {...(props.filtersHeaderReserve !== undefined
+            ? { style: { minBlockSize: props.filtersHeaderReserve } }
+            : {})}
+        >
+          {/* 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
           is its own empty state and the column is open for the host's control
           alone — one empty-state illustration under a working filter is still
@@ -841,6 +1011,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
                 : 16
           }
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+          {...(props.categoryFeaturesPending !== undefined
+            ? { categoryFeaturesPending: props.categoryFeaturesPending }
+            : {})}
           {...(props.renderEmptyExits !== undefined
             ? { renderEmptyExits: props.renderEmptyExits }
             : {})}
@@ -984,7 +1157,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           // has the whole panel on screen beside this row.
           filtersDoor={layout === "sheet"}
           onOpenAll={() => {
-            setSheetOpen(true);
+            setSheetOpen(true, "open");
           }}
         />
       )}
@@ -1021,7 +1194,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 } : {})}
@@ -1040,7 +1213,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)}
@@ -1053,7 +1226,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}
@@ -1094,6 +1267,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     adapter,
     renderCard,
     categoryFeatures,
+    categoryFeaturesPending,
     locale,
     resolveFacetLabels,
     searchBox,
@@ -1106,6 +1280,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     geoOffer,
     footer,
     filtersHeader,
+    filtersHeaderReserve,
     resultsHeader,
     resultsLead,
     categoryFilter,
@@ -1121,6 +1296,8 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     railTop,
     stickyToolbar,
     defaultFiltersOpen,
+    filtersOpen,
+    onFiltersOpenChange,
     pageSize,
     breadcrumb,
     wrapResults,
@@ -1149,6 +1326,9 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(visibleGroups !== undefined ? { visibleGroups } : {})}
           {...(pinnedFacets !== undefined ? { pinnedFacets } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+          {...(categoryFeaturesPending !== undefined
+            ? { categoryFeaturesPending }
+            : {})}
           {...(locale !== undefined ? { locale } : {})}
           {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(searchBox !== undefined ? { searchBox } : {})}
@@ -1160,6 +1340,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(skippedNotice !== undefined ? { skippedNotice } : {})}
           {...(footer !== undefined ? { footer } : {})}
           {...(filtersHeader !== undefined ? { filtersHeader } : {})}
+          {...(filtersHeaderReserve !== undefined ? { filtersHeaderReserve } : {})}
           {...(resultsHeader !== undefined ? { resultsHeader } : {})}
           {...(resultsLead !== undefined ? { resultsLead } : {})}
           {...(categoryFilter !== undefined ? { categoryFilter } : {})}
@@ -1175,6 +1356,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/index.ts

@@ -50,6 +50,9 @@ export {
 export type {
   SearchPageProps,
   SearchFiltersLayout,
+  SearchFiltersHeader,
+  SearchFiltersHeaderSlotProps,
+  SearchFiltersOpenReason,
   SearchRailFrom,
 } from "./SearchPage.js";
 
@@ -122,10 +125,15 @@ export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";
 export {
   FacetGroupControl,
   facetGroupIsEmptyHeading,
+  facetGroupReservedHeight,
   facetGroupShape,
   facetOptionNodes,
   isDictionaryFacet,
   FACET_DICTIONARY_THRESHOLD,
+  FACET_HEADING_HEIGHT,
+  FACET_OPTION_ROW_HEIGHT,
+  FACET_PILLS_PER_ROW,
+  FACET_PILL_ROW_HEIGHT,
   FACET_SHEET_PAGE,
   FACET_VISIBLE_OPTIONS,
 } from "./FacetGroupControl.js";