@stapel/search-react 0.33.1 → 0.35.0

package/src/default/FacetGroupControl.tsx

@@ -62,7 +62,7 @@
  * them visible as before: folding everything would leave a heading over
  * nothing. Chosen options are always visible, wherever their count went.
  */
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 import { Button, Checkbox, Flex, Input, Typography } from "antd";
 import { useT } from "@stapel/core";
@@ -982,6 +982,94 @@ export interface FacetGroupControlProps {
    * only `dictionaryMode: "sheet"` reads it.
    */
   readonly onSetValues?: (slug: string, values: readonly string[]) => void;
+  /**
+   * A newer facet answer is in flight and what is drawn is the previous one —
+   * `FacetPanelBag.refreshing`.
+   *
+   * The group then RESERVES the height it was last measured at
+   * (`min-block-size`), so that whatever changes under it while the answer
+   * settles — an option count, a label the host's vocabulary resolved, an axis
+   * arriving with the category schema — cannot move the groups below it. It is
+   * a floor and never a cap: a group that needs more room still takes it.
+   *
+   * Off (the default), nothing is reserved and nothing is measured.
+   */
+  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;
 }
 
 /**
@@ -1014,6 +1102,46 @@ export function FacetGroupControl(
   const shape = facetGroupShape(group);
   const nodes = facetOptionNodes(group);
 
+  /*
+   * THE GROUP'S OWN FLOOR WHILE AN ANSWER IS IN FLIGHT (p43).
+   *
+   * The rail keeps the previous answer's groups on screen while the next one
+   * loads — `FacetPanelBag.refreshing` — and the shift it was measured at is
+   * what happens INSIDE that window: a group whose option count changes resizes
+   * and takes every group under it with it.
+   *
+   * So each group remembers the height it was last SETTLED at and stands on it
+   * until the answer lands. Its own last height and never a guess: the whole
+   * point is that this box was that tall a moment ago, on this deployment, at
+   * this width, with this category's options in it.
+   *
+   * Measured in an effect and held in a ref: nothing is written during a
+   * 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);
+  const refreshing = props.refreshing === true;
+  useEffect(() => {
+    if (refreshing) return;
+    const node = boxRef.current;
+    // `offsetHeight` is 0 in a layout-free environment (jsdom, a server
+    // render): a floor of zero is not a reservation, so nothing is remembered.
+    if (node !== null && node.offsetHeight > 0) settledHeight.current = node.offsetHeight;
+  });
+
   const disclosure = props.collapsible === true && props.heading !== false;
   const open = !disclosure || openState;
 
@@ -1043,13 +1171,54 @@ 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}
       vertical
       gap={shape === "segmented" ? spacing[2] : spacing[1]}
+      // A FLOOR, not a height: `min-block-size` lets a group that needs more
+      // room take it, and holds the box it had for one that would shrink.
+      {...(reserved !== undefined ? { style: { minBlockSize: reserved } } : {})}
       data-testid={`facet-group-${group.slug}`}
       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, 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
@@ -735,7 +771,26 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
               </GatedButton>
             );
           return (
-          <Flex vertical gap={spacing[3]} data-testid="search-facets">
+          <Flex
+            vertical
+            gap={spacing[3]}
+            data-testid="search-facets"
+            /* THE RAIL SAYS WHEN ITS ANSWER IS IN FLIGHT (p43).
+               A partition press measured 0.0586 CLS here: the rail survives —
+               the groups are the previous answer's and stay mounted — and the
+               groups RESIZE as the new axis's facets land. Each group holds
+               its own floor while this is on (see `FacetGroupControl
+               refreshing`), and the attribute is the host's half: a storefront
+               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.
                 `wrap` is the row's half of the fix: the long sentence drops to
@@ -823,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)}
@@ -851,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={
@@ -1042,6 +1097,10 @@ export function FacetPanelPane(props: FacetPanelPaneProps): ReactElement {
                           group={item.group}
                           onToggle={bag.toggle}
                           onSetValues={bag.setValues}
+                          // Its own last height, held until the answer lands,
+                          // so a group that changes option count does not move
+                          // the groups under it.
+                          refreshing={bag.refreshing}
                           collapsible
                           defaultOpen={
                             needle !== "" ||

package/src/default/SearchPage.tsx

@@ -312,6 +312,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 —
@@ -431,6 +439,22 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * sense that matters and not a decoration bolted on top.
    */
   readonly filtersHeader?: ReactNode;
+  /**
+   * 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.
@@ -679,6 +703,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[];
@@ -787,7 +813,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 +838,28 @@ 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 } }
+            : {})}
+        >
+          {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 +890,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
                 : 16
           }
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
+          {...(props.categoryFeaturesPending !== undefined
+            ? { categoryFeaturesPending: props.categoryFeaturesPending }
+            : {})}
           {...(props.renderEmptyExits !== undefined
             ? { renderEmptyExits: props.renderEmptyExits }
             : {})}
@@ -1094,6 +1146,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     adapter,
     renderCard,
     categoryFeatures,
+    categoryFeaturesPending,
     locale,
     resolveFacetLabels,
     searchBox,
@@ -1106,6 +1159,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     geoOffer,
     footer,
     filtersHeader,
+    filtersHeaderReserve,
     resultsHeader,
     resultsLead,
     categoryFilter,
@@ -1149,6 +1203,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 +1217,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 } : {})}

package/src/default/index.ts

@@ -122,10 +122,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";

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,