@stapel/search-react 0.18.1 → 0.20.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
@@ -139,6 +157,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", paddingInline: 0 };
+
 /**
  * The count, IN the flow.
  *
@@ -179,6 +201,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 +239,7 @@ export function LocationSummaryLine(
   props: LocationSummaryLineProps
 ): ReactElement {
   const t = useT();
-  const { state, activeFilters } = useSearchState();
+  const { state, activeFilters, geoOffer, acceptGeoOffer } = useSearchState();
   const [open, setOpen] = useState(false);
   const geo = state.geo;
 
@@ -221,6 +252,14 @@ 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.geoRadiusKm, { km: geoOffer.radiusKm })
+      : undefined;
+
   const where: ReactNode =
     geo === undefined
       ? t(SEARCH_I18N_KEYS.geoEverywhere)
@@ -272,6 +311,29 @@ export function LocationSummaryLine(
           </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>
+        )}
+
         {/* "Filters", not "All filters": this end of the row shares 390px
             with a place name that can run to fifteen characters, and the word
             the person is looking for is the noun. The panel's own heading
@@ -279,6 +341,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 +365,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,9 +83,11 @@ 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";
+import type { SearchResultsWrapper } from "./SearchResultsPane.js";
 import { SortSelect } from "./SortSelect.js";
 import { SEARCH_BUILTIN_VIEWS, ViewSwitch, resolveView } from "./ViewSwitch.js";
 import type { SearchView } from "./ViewSwitch.js";
@@ -210,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;
   /**
@@ -292,6 +295,13 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * describes rather than over the whole two-column page.
    */
   readonly breadcrumb?: ReactNode;
+  /**
+   * Wrap the results the page drew — a provider, an observer, an analytics
+   * boundary — without taking over the arrangement. Handed straight to
+   * `<SearchResultsPane wrapResults>`; see {@link SearchResultsWrapper} for
+   * why a host cannot do this with `views`/`renderResults` alone.
+   */
+  readonly wrapResults?: SearchResultsWrapper;
   /**
    * The arrangements the view switch offers. Default: the pair's own list and
    * grid. A deployment adds its own — `{ id: "map", labelKey, icon, render }`
@@ -345,6 +355,7 @@ interface SearchPageBodyProps {
   readonly defaultFiltersOpen?: boolean;
   readonly pageSize?: boolean;
   readonly breadcrumb?: ReactNode;
+  readonly wrapResults?: SearchResultsWrapper;
   readonly views?: readonly SearchView[];
   readonly defaultView?: string;
   readonly onViewChange?: (id: string) => void;
@@ -360,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 } : {}),
@@ -420,7 +431,6 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     state.category === undefined &&
     state.lang === undefined &&
     props.renderCategoryFilter === undefined &&
-    props.renderGeoFilter === undefined &&
     (props.languages ?? []).length === 0;
   const showFilters = filtersHeader !== undefined || !filtersEmpty;
 
@@ -451,10 +461,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 }
             : {})}
@@ -503,6 +509,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(phoneToolbar ? { header: "compact" as const } : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
+      {...(props.wrapResults !== undefined ? { wrapResults: props.wrapResults } : {})}
       {...(view.layout !== undefined ? { layout: view.layout } : {})}
       {...(props.renderCard !== undefined ? { renderCard: props.renderCard } : {})}
       {...(props.footer !== undefined ? { footer: props.footer } : {})}
@@ -533,6 +540,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
@@ -565,14 +604,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}
@@ -633,7 +664,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     renderGeoFilter,
     geoLabel,
     skippedNotice,
-    defaultGeo,
+    geoOffer,
     footer,
     filtersHeader,
     resultsHeader,
@@ -643,6 +674,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     defaultFiltersOpen,
     pageSize,
     breadcrumb,
+    wrapResults,
     views,
     defaultView,
     onViewChange,
@@ -654,7 +686,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 } : {})}
@@ -676,6 +708,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(defaultFiltersOpen !== undefined ? { defaultFiltersOpen } : {})}
           {...(pageSize !== undefined ? { pageSize } : {})}
           {...(breadcrumb !== undefined ? { breadcrumb } : {})}
+          {...(wrapResults !== undefined ? { wrapResults } : {})}
           {...(views !== undefined ? { views } : {})}
           {...(defaultView !== undefined ? { defaultView } : {})}
           {...(onViewChange !== undefined ? { onViewChange } : {})}

package/src/default/SearchResultsPane.tsx

@@ -62,6 +62,29 @@ export type SearchResultsRenderer = (
   items: readonly SearchItem[]
 ) => ReactNode;
 
+/**
+ * A wrapper AROUND the results the pane drew, rather than a replacement for
+ * them. It receives the loaded rows and the pane's own rendered arrangement,
+ * and returns whatever should stand in its place — normally a provider with
+ * the arrangement still inside it.
+ *
+ * ```tsx
+ * wrapResults={(rows, results) => (
+ *   <ListingEngagementScope ids={rows.map((row) => Number(row.key))}>
+ *     {results}
+ *   </ListingEngagementScope>
+ * )}
+ * ```
+ *
+ * Called only on the LOADED arm: there are no rows to scope while a search is
+ * in flight, has failed, or found nothing, and the pane's four load arms stay
+ * the pane's own sentences.
+ */
+export type SearchResultsWrapper = (
+  items: readonly SearchItem[],
+  results: ReactNode
+) => ReactNode;
+
 /**
  * The widest a column of results is allowed to get.
  *
@@ -128,6 +151,24 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * when the container's arrangement is not "cards in a grid".
    */
   readonly renderResults?: SearchResultsRenderer;
+  /**
+   * The scope slot: WRAPS the arrangement instead of replacing it.
+   *
+   * A container that needs to publish something over the rows the pane just
+   * drew — a per-reader overlay, an intersection observer, an analytics
+   * boundary — needs the rows AND the pane's own grid, and `renderResults`
+   * only offers the first at the price of the second.
+   *
+   * The measured cost of not having it: a storefront that dims already-seen
+   * listings could open its engagement scope on its own landing feed (which
+   * mounts the pane directly) and NOT on `/s` or `/c/:slug`, which reach the
+   * pane through `<SearchPage>` and its internal `<SearchStateProvider>` —
+   * so the feature worked on one of the three screens a buyer scrolls and
+   * silently did nothing on the other two (walker D105). Re-implementing the
+   * grid to get the rows was the only way through, and a host's copy of this
+   * pane's grid is a copy that stops tracking it.
+   */
+  readonly wrapResults?: SearchResultsWrapper;
   /**
    * Rendered beside the count in the heading row — the sort control, a view
    * switch. The pane owns the heading, so a screen that composes it hands its
@@ -284,7 +325,7 @@ function Pager(props: { bag: SearchResultsBag }): ReactElement | null {
 
 export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
   const t = useT();
-  const { renderCard, renderResults } = props;
+  const { renderCard, renderResults, wrapResults } = props;
   const scorerName = useScorerNames();
   const maxWidth = props.maxWidth === undefined ? RESULTS_MAX_WIDTH : props.maxWidth;
 
@@ -377,9 +418,9 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                 );
               }}
             >
-              {(items) => (
-                <div data-testid="search-results">
-                  {renderResults !== undefined ? (
+              {(items) => {
+                const arrangement =
+                  renderResults !== undefined ? (
                     renderResults(items)
                   ) : (
                     <div
@@ -397,9 +438,15 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                         </div>
                       ))}
                     </div>
-                  )}
-                </div>
-              )}
+                  );
+                return (
+                  <div data-testid="search-results">
+                    {wrapResults !== undefined
+                      ? wrapResults(items, arrangement)
+                      : arrangement}
+                  </div>
+                );
+              }}
             </LoadList>
 
             <Pager bag={bag} />

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.
@@ -46,6 +47,7 @@ export { SearchResultsPane, RESULTS_MAX_WIDTH } from "./SearchResultsPane.js";
 export type {
   SearchResultsPaneProps,
   SearchResultsRenderer,
+  SearchResultsWrapper,
 } from "./SearchResultsPane.js";
 
 export {