@stapel/search-react 0.19.0 → 0.21.0

package/src/default/LocationSummaryLine.tsx

@@ -23,6 +23,24 @@
  * applied it says the search is looking everywhere, which is the truth and is
  * also the invitation to narrow it.
  *
+ * ## The offer, and why it is a BUTTON on this row
+ *
+ * A visitor whose browser has already granted geolocation is one the host can
+ * place precisely — and for a long time this pair took that as licence to
+ * place them, through a `defaultGeo` that wrote a 25 km radius into the URL
+ * before anybody had said anything (see {@link SearchStateProviderProps.geoOffer}
+ * for what that cost: whole category leaves reading "nothing found" while
+ * their stock sat 30 km away). The position is still worth having. It is just
+ * not the pair's to apply.
+ *
+ * So the offer lands HERE, on the one row that is on screen at every width
+ * without opening a sheet, beside the sentence it would change ("searching
+ * everywhere" → "within 25 km of you"). It states its own radius, because a
+ * button that says only "near me" is asking a person to accept a number they
+ * cannot see; and the moment it is pressed the radius becomes the ordinary
+ * adjustable one in the panel, and the location becomes an ordinary chip with
+ * an ordinary way off.
+ *
  * ## The right-hand affordance carries a COUNT, and the chip row carries a dot
  *
  * `<FilterChips>`'s leading chip is a 32px circle: a number inside it is a
@@ -76,6 +94,9 @@ import { GeoSheet, SUMMARY_GEO_TEST_IDS } from "./geoSheet.js";
 
 /** The class the row carries, for {@link locationLineCss}. */
 export const LOCATION_LINE_CLASS = "stapel-search-location-line";
+/** The class the ONE location control carries — the place and the offer,
+ * inside a single box. See {@link locationLineCss} for what it fixes. */
+export const LOCATION_LINE_GROUP_CLASS = "stapel-search-location-line-group";
 /** The class the shrinking half carries. */
 export const LOCATION_LINE_WHERE_CLASS = "stapel-search-location-line-where";
 /** The class the truncating label carries. */
@@ -99,6 +120,7 @@ export function locationLineCss(): string {
   const where = `.${LOCATION_LINE_WHERE_CLASS}`;
   const label = `.${LOCATION_LINE_LABEL_CLASS}`;
   const end = `.${LOCATION_LINE_END_CLASS}`;
+  const group = `.${LOCATION_LINE_GROUP_CLASS}`;
   return [
     // `min-width:0` on the row too: a flex item's default `min-width:auto`
     // is what makes a nested flex row refuse to shrink at all.
@@ -121,6 +143,35 @@ export function locationLineCss(): string {
       `text-overflow:ellipsis;white-space:nowrap}`,
     // The word a person is looking for never loses a pixel to a place name.
     `${end}{flex:0 0 auto}`,
+    // ── ONE control, not two red links at opposite ends of the page ────────
+    //
+    // Measured on a live 1440px leaf: the row is 992px wide, "📍 Searching
+    // everywhere" sat at x=370 and "Near me · Within 25 km" at x=776, both
+    // drawn in the same brand red, with ~400px of air between them and
+    // nothing — no border, no ground, no heading — saying they were about the
+    // same thing. Two identical-looking links at opposite ends of a strip are
+    // read as two unrelated controls, which is what they looked like.
+    //
+    // So the place and the offer share ONE box with a border and a ground,
+    // sitting together at the leading edge, with a hairline between them: the
+    // eye gets a single object that says where this search is looking and
+    // offers the one move that would change it. The border comes from the
+    // role token, so it is right in both themes by construction.
+    // `min-inline-size:0` explicitly, and `flex-shrink` on the box rather
+    // than on its contents: a flex item's `min-width:auto` refuses to go
+    // below its own content, so without this the group pushed the filters
+    // door off the end of a 390px row instead of letting the place name give
+    // way — which is the half that can.
+    `${group}{display:flex;align-items:stretch;flex:0 1 auto;min-inline-size:0;` +
+      `border:1px solid ${cssVar("border")};border-radius:${String(radii.md)}px;` +
+      `background:${cssVar("surface-raised")};overflow:hidden}`,
+    // The two halves are separated by the box's own line, never by a gap: a
+    // gap inside a bordered group reads as two groups again.
+    `${group}>*+*{border-inline-start:1px solid ${cssVar("border")}}`,
+    `${group}>*{border-radius:0}`,
+    // Both halves pay for their own breathing room; the antd Button's inline
+    // padding is zeroed above so the box, not the button, sets the measure.
+    `${group}>*{padding-inline:${String(spacing[2])}px}`,
   ].join("");
 }
 
@@ -131,7 +182,9 @@ const ROW: CSSProperties = { width: "100%" };
 /** The shrinking half. The flex rules it needs live in the hoisted sheet
  * (they have to reach antd's own wrapper span); this is the chrome. */
 const LOCATION: CSSProperties = {
-  paddingInline: 0,
+  // No `paddingInline` here: the group's sheet sets it for both halves, and
+  // an inline style would beat the sheet and leave one half flush against the
+  // border while the other breathed.
   textAlign: "start",
 };
 
@@ -139,6 +192,10 @@ const LOCATION: CSSProperties = {
  * noise, and it costs 16px. */
 const PIN: CSSProperties = { flex: "0 0 auto", display: "inline-flex" };
 
+/** The offer. It never shrinks: it is three words and a number, and half of
+ * "Near me" is not an offer. */
+const OFFER: CSSProperties = { flex: "0 0 auto" };
+
 /**
  * The count, IN the flow.
  *
@@ -179,6 +236,15 @@ export interface LocationSummaryLineProps {
    * because the surface is what it covers.
    */
   readonly onOpenAll: () => void;
+  /**
+   * Draw the trailing "Filters (N)" door. Default `true`.
+   *
+   * `false` where the panel is ALREADY on screen — a desktop column layout —
+   * because a door beside the room it opens is not a door, and the count it
+   * carries is printed again on the panel's own "clear all" a few hundred
+   * pixels to the left.
+   */
+  readonly filtersDoor?: boolean;
 }
 
 /** A map pin in `currentColor` — the house convention: an inline monochrome
@@ -208,7 +274,8 @@ export function LocationSummaryLine(
   props: LocationSummaryLineProps
 ): ReactElement {
   const t = useT();
-  const { state, activeFilters } = useSearchState();
+  const { state, activeFilters, geoOffer, geoIsOffer, acceptGeoOffer } =
+    useSearchState();
   const [open, setOpen] = useState(false);
   const geo = state.geo;
 
@@ -221,10 +288,30 @@ export function LocationSummaryLine(
       ? t(SEARCH_I18N_KEYS.geoRadiusKm, { km: geo.radiusKm })
       : undefined;
 
+  // The offer's own radius, said out loud on the button. `geoOffer` is
+  // already `undefined` whenever a location is applied (the provider closes
+  // the question), so this row never shows an offer beside a place.
+  const offerRadius =
+    geoOffer !== undefined && geoOffer.kind === "center" && geoOffer.radiusKm !== undefined
+      ? t(SEARCH_I18N_KEYS.geoRadiusKmShort, { km: geoOffer.radiusKm })
+      : undefined;
+
+  // What the line CALLS the place it is looking at.
+  //
+  // The host's name wins — it is the only one that can be checked by a reader
+  // — then the fact the provider holds, and only then the shape of the
+  // constraint. The middle arm is D184's second half: pressing "Near me"
+  // turned this line into "A chosen place on the map" for a person who had
+  // never opened a map. `geoIsOffer` is the provider reporting how the search
+  // came to be here, rather than this file inferring it from three numbers
+  // that look the same whatever produced them.
   const where: ReactNode =
     geo === undefined
       ? t(SEARCH_I18N_KEYS.geoEverywhere)
-      : (props.geoLabel ?? geoSummaryFallback(geo, t));
+      : (props.geoLabel ??
+        (geoIsOffer
+          ? t(SEARCH_I18N_KEYS.geoNearYou)
+          : geoSummaryFallback(geo, t)));
 
   return (
     <>
@@ -240,37 +327,73 @@ export function LocationSummaryLine(
         data-testid="search-location-summary"
         data-geo={geo === undefined ? "off" : "on"}
       >
-        {/* The glyph is rendered as a CHILD rather than through antd's `icon`
-            prop: the icon slot sits outside the wrapper span, so the label
-            beside it could not be given a min-width of its own — and a label
-            that cannot shrink is a label that overflows. */}
-        <Button
-          type="link"
-          style={LOCATION}
-          className={LOCATION_LINE_WHERE_CLASS}
-          data-testid="search-location-open"
-          data-analytics="none"
-          data-analytics-reason="opening the location sheet is a read, not a flow step"
-          onClick={() => {
-            setOpen(true);
-          }}
+        {/* ONE control: where this search is looking, and — while the
+            question is still open — the one move that would change it. See
+            `locationLineCss` for the measurement that made them one box. */}
+        <div
+          className={LOCATION_LINE_GROUP_CLASS}
+          data-testid="search-location-group"
         >
-          <span style={PIN}>
-            <PinGlyph />
-          </span>
-          <span
-            className={LOCATION_LINE_LABEL_CLASS}
-            data-testid="search-location-label"
+          {/* The glyph is rendered as a CHILD rather than through antd's
+              `icon` prop: the icon slot sits outside the wrapper span, so the
+              label beside it could not be given a min-width of its own — and
+              a label that cannot shrink is a label that overflows.
+
+              `type="text"`, not `type="link"`: this half is a STATEMENT about
+              where the search is looking, and painting it the brand colour
+              made it indistinguishable from the offer beside it. The offer
+              keeps the colour, because the offer is the action. */}
+          <Button
+            type="text"
+            style={LOCATION}
+            className={LOCATION_LINE_WHERE_CLASS}
+            data-testid="search-location-open"
+            data-analytics="none"
+            data-analytics-reason="opening the location sheet is a read, not a flow step"
+            onClick={() => {
+              setOpen(true);
+            }}
           >
-            {where}
-            {radius !== undefined && (
-              <span data-testid="search-location-radius">
-                {" · "}
-                {radius}
-              </span>
-            )}
-          </span>
-        </Button>
+            <span style={PIN}>
+              <PinGlyph />
+            </span>
+            <span
+              className={LOCATION_LINE_LABEL_CLASS}
+              data-testid="search-location-label"
+            >
+              {where}
+              {radius !== undefined && (
+                <span data-testid="search-location-radius">
+                  {" · "}
+                  {radius}
+                </span>
+              )}
+            </span>
+          </Button>
+
+          {/* The offer, and nothing is applied until it is pressed. Drawn only
+              when the host has a position to offer AND the search carries no
+              location of its own — the provider enforces the second half, so
+              this is one condition, not two that could disagree. */}
+          {geoOffer !== undefined && (
+            <Button
+              type="link"
+              style={OFFER}
+              data-testid="search-location-offer"
+              data-analytics="none"
+              data-analytics-reason="applying a filter the person pressed is search state, and search state is the URL"
+              onClick={acceptGeoOffer}
+            >
+              {t(SEARCH_I18N_KEYS.geoNearMe)}
+              {offerRadius !== undefined && (
+                <span data-testid="search-location-offer-radius">
+                  {" · "}
+                  {offerRadius}
+                </span>
+              )}
+            </Button>
+          )}
+        </div>
 
         {/* "Filters", not "All filters": this end of the row shares 390px
             with a place name that can run to fifteen characters, and the word
@@ -279,6 +402,7 @@ export function LocationSummaryLine(
             door. */}
         {/* The count, not a dot: this row has the width to say how many — and
             it rides IN the line rather than floating off its corner. */}
+        {props.filtersDoor === false ? null : (
         <Flex
           align="center"
           gap={spacing[1]}
@@ -302,6 +426,7 @@ export function LocationSummaryLine(
             </span>
           )}
         </Flex>
+        )}
       </Flex>
 
       <GeoSheet

package/src/default/SearchPage.tsx

@@ -35,17 +35,17 @@
  *
  * ── Where the search opens, and what it calls the place ───────────────────
  *
- * `defaultGeo` centres a fresh search on the visitor — a granted browser
- * prompt, or the server's IP guess when there was none — and `geoLabel` says
- * what that place is CALLED. Both are the host's to resolve: this page has a
- * `lat` and a `lon` in its query string and no way on earth to turn them into
- * "Berlin Mitte", which is exactly why it must not print them. A search
- * package that grew a geocoder to say a nicer sentence would have taken on the
- * whole of `geo-react` to avoid one bad line.
+ * `geoOffer` is a place this search COULD be narrowed to — the visitor's own
+ * position, as the host resolved it — and `geoLabel` says what the place a
+ * search is ALREADY narrowed to is CALLED. Both are the host's to resolve:
+ * this page has a `lat` and a `lon` in its query string and no way on earth to
+ * turn them into "Berlin Mitte", which is exactly why it must not print them.
+ * A search package that grew a geocoder to say a nicer sentence would have
+ * taken on the whole of `geo-react` to avoid one bad line.
  *
- * The centring is applied once, only into a URL that carries no location, and
- * never again after the visitor has said anything about location themselves —
- * see {@link SearchStateProviderProps.defaultGeo}, which owns the rules.
+ * The offer is never applied on the page's own initiative: it is drawn as a
+ * button on the location row, and pressing it is the person's word. See
+ * {@link SearchStateProviderProps.geoOffer} for the defect that shape closes.
  *
  * ── The filter column is laid out only when there is something in it ──────
  *
@@ -83,6 +83,7 @@ import type {
   GeoFilterSlotProps,
 } from "./FacetPanelPane.js";
 import { FilterChips } from "./FilterChips.js";
+import { LocationSummaryLine } from "./LocationSummaryLine.js";
 import { PageSizeSelect } from "./PageSizeSelect.js";
 import { SearchBox } from "./SearchBox.js";
 import { SearchResultsPane } from "./SearchResultsPane.js";
@@ -211,16 +212,17 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * Default `false` — see {@link FacetPanelPaneProps.skippedNotice}. */
   readonly skippedNotice?: boolean;
   /**
-   * Open the search centred where the visitor is, when the URL says nothing
-   * about location — see {@link SearchStateProviderProps.defaultGeo} for the
-   * four rules that keep it from overruling a link or a person.
+   * A location this search could be narrowed to, OFFERED to the visitor — see
+   * {@link SearchStateProviderProps.geoOffer} for why it is an offer and not a
+   * default, and for the defect that distinction closes.
    *
    * The host resolves the position; this page does not know what a map or a
    * geocoder is and must not learn. A browser prompt (`usePermission`
    * + `geolocation`) or the server's IP guess both arrive here as the same two
-   * numbers, and `geoLabel` is where the name of the place they mean comes in.
+   * numbers. Nothing is applied until the person presses the offer, and
+   * `geoOfferLabel` is what the button calls the place.
    */
-  readonly defaultGeo?: SearchGeo | undefined;
+  readonly geoOffer?: SearchGeo | undefined;
   /** Container chrome under the results — e.g. the ranking-disclosure link. */
   readonly footer?: ReactNode;
   /**
@@ -369,7 +371,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const t = useT();
   const tPlural = useTPlural();
   const { categoryFeatures, locale, resolveFacetLabels, filtersHeader } = props;
-  const { state } = useSearchState();
+  const { state, geoOffer } = useSearchState();
   const facets = useFacetPanel({
     ...(categoryFeatures !== undefined ? { categoryFeatures } : {}),
     ...(locale !== undefined ? { locale } : {}),
@@ -424,12 +426,16 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const filtersEmpty =
     facets.state.status === "ready" &&
     facets.state.data.length === 0 &&
+    // Zero groups is not zero filters: `withheld` names groups the server
+    // counted and held back for covering too little of the result set, and
+    // the panel's job is to say how many (D175). Skipping the column would
+    // put that sentence nowhere.
+    facets.withheld.length === 0 &&
     facets.activeFilters === 0 &&
     ranges.length === 0 &&
     state.category === undefined &&
     state.lang === undefined &&
     props.renderCategoryFilter === undefined &&
-    props.renderGeoFilter === undefined &&
     (props.languages ?? []).length === 0;
   const showFilters = filtersHeader !== undefined || !filtersEmpty;
 
@@ -460,10 +466,6 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           {...(props.renderCategoryFilter !== undefined
             ? { renderCategoryFilter: props.renderCategoryFilter }
             : {})}
-          {...(props.renderGeoFilter !== undefined
-            ? { renderGeoFilter: props.renderGeoFilter }
-            : {})}
-          {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
           {...(props.skippedNotice !== undefined
             ? { skippedNotice: props.skippedNotice }
             : {})}
@@ -543,6 +545,38 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       )}
       <UrlIssueNotice />
 
+      {/* THE LOCATION CONTROL — a place, its radius, and the way to change
+          either. Mounted by the PAGE, not by each host, which is how a
+          category results page came to have no way to say where it was
+          looking while `/s` had one: the row was a slot every surface had to
+          remember to fill, and one of them did not.
+
+          Drawn when this deployment can resolve a place at all, or when the
+          address already carries one (a shared link must always be widenable
+          by whoever opens it). It is not a filter and it is not in the filter
+          count — see `activeFilterCount`.
+
+          Three reasons to draw it, and an offer is one of them: a deployment
+          that can place its visitor but ships no place picker still needs
+          somewhere for them to accept — otherwise the offer is a value with
+          no control, which is the same silence this pack is about. */}
+      {(props.renderGeoFilter !== undefined ||
+        state.geo !== undefined ||
+        geoOffer !== undefined) && (
+        <LocationSummaryLine
+          {...(props.renderGeoFilter !== undefined
+            ? { renderGeoFilter: props.renderGeoFilter }
+            : {})}
+          {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+          // No door where the room is already open: the desktop column layout
+          // has the whole panel on screen beside this row.
+          filtersDoor={layout === "sheet"}
+          onOpenAll={() => {
+            setSheetOpen(true);
+          }}
+        />
+      )}
+
       {/* Above the chips in the sheet layout and above the columns in the
           other one — see {@link SearchPageProps.resultsHeader}. `?? null` is
           the written decision, not an oversight: a page with nothing to say
@@ -575,14 +609,6 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             {...(props.categoryLabel !== undefined
               ? { categoryLabel: props.categoryLabel }
               : {})}
-            {...(props.renderGeoFilter !== undefined
-              ? { renderGeoFilter: props.renderGeoFilter }
-              : {})}
-            {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
-            /* The row above already states the location and opens its own
-               sheet, so the chip would be the second control over one filter
-               — see `FilterChipsProps.geoChip`. */
-            {...(props.resultsHeader !== undefined ? { geoChip: false } : {})}
           />
           <SkinDialog
             open={sheetOpen}
@@ -643,7 +669,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     renderGeoFilter,
     geoLabel,
     skippedNotice,
-    defaultGeo,
+    geoOffer,
     footer,
     filtersHeader,
     resultsHeader,
@@ -665,7 +691,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
 
   return (
     <SkinTheme surface="base" {...(mode !== undefined ? { mode } : {})}>
-      <SearchStateProvider adapter={adapter} defaultGeo={defaultGeo} {...parseOptions}>
+      <SearchStateProvider adapter={adapter} geoOffer={geoOffer} {...parseOptions}>
         <SearchPageBody
           {...(renderCard !== undefined ? { renderCard } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}

package/src/default/geoSheet.tsx

@@ -1,12 +1,17 @@
 /**
  * The LOCATION sheet — one implementation, two doors.
  *
- * `<FilterChips>`'s geo chip opened it and `<LocationSummaryLine>` opens it
- * too: on the ref's SERP both controls say where the search is centred, one
- * on the summary row and one in the chip strip, and a person tapping either
- * must land in the same place. Two copies of a bottom sheet is two places for
- * "clear the location" to behave differently, so the sheet is a component and
- * the two surfaces are two `open` flags on it.
+ * ONE control, and this is the inside of it. `<LocationSummaryLine>` is the
+ * door: a place on the left, its radius beside it, and this sheet behind
+ * both.
+ *
+ * It used to be three doors — the chip row's geo chip, the facet panel's
+ * "Location" group, and the row — over one pair of numbers, with the radius
+ * living in the panel and the place in the sheet. That arrangement made a
+ * latitude look like a filter, which is what it is not: a coordinate pair is
+ * the machine form of a place, and a place with a radius is its own thing in
+ * the chrome, like the search box. The chip and the panel group are gone; the
+ * radius moved in here, beside the place it is a radius OF.
  *
  * ── What the sheet can do without a geocoder, and what it cannot ───────────
  *
@@ -25,7 +30,7 @@
  * the DOM, on either surface.
  */
 import type { ReactElement, ReactNode } from "react";
-import { Button, Flex, Typography } from "antd";
+import { Button, Flex, InputNumber, Typography } from "antd";
 import { SkinDialog } from "@stapel/tokens-antd/skin";
 import { SlotPlaceholder, useT, useTPlural } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
@@ -42,6 +47,7 @@ export interface GeoSheetTestIds {
   readonly apply: string;
   readonly slot: string;
   readonly summary: string;
+  readonly radius: string;
   readonly clear: string;
 }
 
@@ -53,6 +59,7 @@ export const CHIP_GEO_TEST_IDS: GeoSheetTestIds = {
   apply: "filter-chip-apply-geo",
   slot: "search-chip-geo-slot",
   summary: "search-chip-geo-summary",
+  radius: "search-chip-geo-radius",
   clear: "search-chip-geo-clear",
 };
 
@@ -63,6 +70,9 @@ export const SUMMARY_GEO_TEST_IDS: GeoSheetTestIds = {
   apply: "search-location-apply",
   slot: "search-location-slot",
   summary: "search-location-sheet-summary",
+  // The one radius control in the pair. It was `search-geo-radius` in the
+  // facet panel, which no longer draws a location group at all.
+  radius: "search-geo-radius",
   clear: "search-location-clear",
 };
 
@@ -142,6 +152,35 @@ export function GeoSheet(props: GeoSheetProps): ReactElement {
             <Typography.Text type="secondary" data-testid={props.testIds.summary}>
               {summary}
             </Typography.Text>
+            {/* HOW WIDE, beside WHERE. A radius means nothing without a place,
+                so this exists only once one is set and disappears with it —
+                and it lives here rather than in the filter panel, where it was
+                a number about a place the panel could not name. */}
+            {geo.kind === "center" && (
+              <Flex vertical gap={spacing[1]}>
+                <Typography.Text type="secondary">
+                  {t(SEARCH_I18N_KEYS.geoRadiusLabel)}
+                </Typography.Text>
+                <InputNumber
+                  min={1}
+                  style={{ alignSelf: "flex-start" }}
+                  value={geo.radiusKm ?? null}
+                  aria-label={t(SEARCH_I18N_KEYS.geoRadiusLabel)}
+                  data-testid={props.testIds.radius}
+                  onChange={(value) => {
+                    setGeo({
+                      kind: "center",
+                      lat: geo.lat,
+                      lon: geo.lon,
+                      ...(typeof value === "number" ? { radiusKm: value } : {}),
+                    });
+                  }}
+                />
+              </Flex>
+            )}
+            {/* One control off. Clearing the place clears the radius with it —
+                `setGeo(null)` drops both, because half a location is not a
+                state this search can be in. */}
             <Button
               style={{ alignSelf: "flex-start" }}
               data-testid={props.testIds.clear}

package/src/default/index.ts

@@ -24,9 +24,10 @@
  *     keeps the controls that WIDEN a location a link already carries. Its two
  *     companions divide the same seam the same way: `geoLabel` is what the
  *     current place is CALLED (owning a coordinate is not permission to print
- *     one), and `defaultGeo` is where a fresh search opens when the URL names
- *     nowhere — the visitor's own position, resolved by whoever is allowed to
- *     ask for it.
+ *     one), and `geoOffer` is a place the search COULD be narrowed to — the
+ *     visitor's own position, resolved by whoever is allowed to ask for it,
+ *     drawn as an invitation on the location row and applied only when
+ *     somebody presses it.
  *  5. **retheming through the §68 token JSON** — every surface wraps itself
  *     in the shared `SkinTheme`, so a host's regenerated `--stapel-*` custom
  *     properties reach this skin with zero code.

package/src/headless/FacetPanel.tsx

@@ -2,9 +2,15 @@ import type { ReactNode } from "react";
 import { loadStateFromQuery, mapLoad, useT } from "@stapel/core";
 import type { LoadState } from "@stapel/core";
 import type { FeatureDef } from "@stapel/attributes-react";
-import type { FacetMeta, SearchRange } from "../api/types.js";
+import type {
+  FacetCategoryCount,
+  FacetMeta,
+  FacetWithheldGroup,
+  SearchRange,
+} from "../api/types.js";
 import { useSearchQuery } from "../model/queries.js";
 import { buildFacetGroups } from "../state/facets.js";
+import { FACET_PLAN_EVIDENCE } from "../state/degradations.js";
 import type { FacetGroup } from "../state/facets.js";
 import { useHostFacetLabels } from "./useFacetLabels.js";
 import type { FacetLabelResolver } from "./useFacetLabels.js";
@@ -51,6 +57,34 @@ export interface FacetPanelBag {
   readonly currency: string | undefined;
   /** Size of the largest counted set — the number `approximate` is about. */
   readonly candidates: number;
+  /**
+   * Groups the counter COUNTED and then held back, because their buckets
+   * describe too little of the result set. Not empty means the panel may
+   * NOT say "this search offers no filters" — it says how many, instead.
+   */
+  readonly withheld: readonly FacetWithheldGroup[];
+  /**
+   * The categories this answer's candidate set is made of, busiest first —
+   * the evidence the plan was drawn from, and the counted category filter a
+   * text search has no other way to offer. Empty when the plan is the
+   * queried category's own. `category` is the same slash-joined id path
+   * `SearchQueryState.category` takes.
+   */
+  readonly categories: readonly FacetCategoryCount[];
+  /**
+   * Where the plan came from: `"category"` (the queried category's own
+   * authored schema) or `"evidence"` (the categories the candidate set
+   * actually contains).
+   */
+  readonly plan: string;
+  /**
+   * True when the server could not work out a plan AT ALL — the engine has
+   * no `category_counts` verb (`degraded: ["facet_plan_evidence"]`). An
+   * empty panel then means "we do not know", so a skin must not print
+   * "there are no filters" over it; the degradation notice is what tells
+   * the reader.
+   */
+  readonly planUnavailable: boolean;
   /** Facet values + ranges + geo currently applied. */
   readonly activeFilters: number;
 
@@ -67,6 +101,9 @@ const EMPTY_META: FacetMeta = {
   skipped: [],
   dropped_filters: [],
   core_ranges: [],
+  plan: "category",
+  withheld: [],
+  categories: [],
 };
 
 /**
@@ -174,6 +211,17 @@ export function useFacetPanel(props: {
             ?.card?.["currency"] as string | undefined
         : undefined,
     candidates: meta.candidates,
+    withheld: meta.withheld ?? [],
+    categories: meta.categories ?? [],
+    plan: meta.plan ?? "category",
+    // Read off the raw list rather than through `parseDegradations`: the
+    // question is whether THIS answer supports the sentence "no filters",
+    // and the banner's own parsing is a different job on a different
+    // surface. Guarded on the READY state, never flattened — a query still
+    // in flight has not said anything about its facet plan.
+    planUnavailable:
+      envelope.status === "ready" &&
+      envelope.data.degraded.includes(FACET_PLAN_EVIDENCE),
     activeFilters,
     toggle: toggleFilter,
     setRange,