@stapel/search-react 0.19.0 → 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,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 } : {}),
@@ -429,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;
 
@@ -460,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 }
             : {})}
@@ -543,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
@@ -575,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}
@@ -643,7 +664,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     renderGeoFilter,
     geoLabel,
     skippedNotice,
-    defaultGeo,
+    geoOffer,
     footer,
     filtersHeader,
     resultsHeader,
@@ -665,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 } : {})}

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/SearchStateProvider.tsx

@@ -2,9 +2,7 @@ import {
   createContext,
   useCallback,
   useContext,
-  useEffect,
   useMemo,
-  useRef,
 } from "react";
 import type { ReactElement, ReactNode } from "react";
 import type {
@@ -57,8 +55,22 @@ export interface SearchStateBag {
   readonly state: SearchQueryState;
   /** What the URL carried that could not be read (see `SearchStateIssue`). */
   readonly issues: readonly SearchStateIssue[];
-  /** Facet values + ranges + geo the person has applied. */
+  /** Facet values + ranges + geo the person has applied.
+   *
+   * Everything counted here was chosen BY the person: this pair applies no
+   * filter of its own, so the number beside "clear all" can never be one the
+   * reader has to go hunting for.
+   */
   readonly activeFilters: number;
+  /**
+   * A location the host can narrow to, which nobody has accepted yet —
+   * `undefined` when the host offers none, or when the search already carries
+   * a location of its own (an offer would then be a second answer to a
+   * question already answered).
+   *
+   * Draw it as an invitation ("near me"), never as state.
+   */
+  readonly geoOffer: SearchGeo | undefined;
 
   setText(q: string): void;
   setSort(sort: string | null): void;
@@ -72,6 +84,9 @@ export interface SearchStateBag {
   clearAll(): void;
   /** Move to a keyset page. The ONLY mutator that keeps a cursor. */
   goToAnchor(anchor: string | null, direction: "next" | "prev"): void;
+  /** Accept {@link geoOffer}. A no-op when there is nothing on offer, so a
+   * control can be pressed without first re-checking what this bag says. */
+  acceptGeoOffer(): void;
   /** Escape hatch for a host control this pair does not ship. Goes through
    * `patchSearchState`, so it drops the cursor like every other change. */
   patch(patch: SearchStatePatch): void;
@@ -82,40 +97,35 @@ const StateContext = createContext<SearchStateBag | null>(null);
 export interface SearchStateProviderProps extends ParseSearchStateOptions {
   readonly adapter: SearchParamsAdapter;
   /**
-   * Where to centre the results when the URL says nothing about location —
-   * the visitor's own position, as the HOST resolved it (a granted browser
-   * geolocation prompt, or the server's IP guess when there was none).
+   * A location this search COULD be narrowed to — offered, never applied.
    *
-   * Opt-in, and it is deliberately not one of the `default*` parse options
-   * beside it. Those are read-time fallbacks: `defaultCategory` fills a gap in
-   * the parsed state and never reaches the query string. A location cannot
-   * work that way. It has to be WRITTEN, once, because the URL is the state:
-   * a centre that lived only in the parse would vanish from a link the visitor
-   * shares, and — worse — would be re-applied on the very next render after
-   * they cleared it, which is a filter that will not come off.
+   * The host resolves it (a granted browser prompt, the server's IP guess);
+   * this provider does nothing with it except hand it back on the bag as
+   * {@link SearchStateBag.geoOffer}, so a control can draw "near me" and the
+   * PERSON decides. Nothing is written to the URL until they press it.
    *
-   * So the rules, all four of which are about not overruling a person:
+   * ## Why this is an offer and not a default (defect: a silent radius)
    *
-   *  - **Only into an empty URL.** A link that carries `lat`/`lon` or `bbox`
-   *    already means a place, and it must mean the same place for everybody
-   *    who opens it. A default that overwrote it would make one address bar
-   *    two different searches.
-   *  - **Once.** Tracked as "has anyone spoken about location yet", in a ref —
-   *    not by comparing the default against the current value, which cannot
-   *    tell "the visitor cleared it" from "it has not been applied".
-   *  - **Never after a clear.** `setGeo` marks the question answered, so a
-   *    person who widens the search back to everywhere stays there.
-   *  - **Late is fine.** A browser prompt and an IP round trip both resolve
-   *    after the first paint, so `undefined` now and a value three renders
-   *    later still applies — provided the URL is still empty of geo at that
-   *    moment.
+   * The previous shape of this prop (`defaultGeo`) wrote the visitor's
+   * position into the query string on the first render that could, under four
+   * careful rules about not overruling a person. Every rule held, and the
+   * result was still a filter nobody asked for: a browser permission granted
+   * once, for one map, became a permanent 25 km wall around every category
+   * leaf and every result page in the deployment. Measured on a live board:
+   * 48 phones became 17, and three leaves with stock became "nothing found".
+   * The page looks perfectly healthy while doing it, which is what makes it
+   * dangerous — the honest reading of an empty leaf is "this board is empty",
+   * not "your browser told us where you are".
    *
-   * It REPLACES the history entry rather than pushing one: the visitor did not
-   * perform this change, and Back should leave the page, not undo a centring
-   * they never asked for. The adapter's `setParams` takes `{ replace: true }`
-   * for exactly this, and the react-router binding honours it.
+   * There is no set of rules that fixes that, because the defect is not in
+   * the rules: applying a spatial filter is a decision about what the person
+   * wants to see, and only they hold it. So the prop carries the same value
+   * and the provider no longer commits it. Two more defects fall out with it:
+   * the URL is never rewritten behind the visitor (a hand-typed `radius_km`
+   * survives), and the results are fetched ONCE instead of being fetched and
+   * immediately superseded by a second, narrower query.
    */
-  readonly defaultGeo?: SearchGeo | undefined;
+  readonly geoOffer?: SearchGeo | undefined;
   readonly children: ReactNode;
 }
 
@@ -128,7 +138,7 @@ export interface SearchStateProviderProps extends ParseSearchStateOptions {
 export function SearchStateProvider(
   props: SearchStateProviderProps
 ): ReactElement {
-  const { adapter, children, defaultGeo, ...parseOptions } = props;
+  const { adapter, children, geoOffer, ...parseOptions } = props;
   const { params, setParams } = adapter;
 
   // The parse options are spread into a stable dependency: a host that builds
@@ -165,16 +175,6 @@ export function SearchStateProvider(
     [setParams, search]
   );
 
-  /**
-   * Has anything at all said where to search yet?
-   *
-   * `true` once the URL was seen carrying a location, once `defaultGeo` has
-   * been applied, or once anybody called `setGeo` — including with `null`.
-   * That last one is the whole reason this is a ref and not a comparison: a
-   * cleared location and an unapplied default look identical in the state, and
-   * only the record of who spoke tells them apart.
-   */
-  const geoSettled = useRef(false);
 
   const bag = useMemo<SearchStateBag>(() => {
     const state = parsed.state;
@@ -188,6 +188,12 @@ export function SearchStateProvider(
       state,
       issues: parsed.issues,
       activeFilters: activeFilterCount(state),
+      // An offer stands only while the question is open. Once the search
+      // carries a place — from a link, or because somebody pressed the offer
+      // — there is nothing left to offer, and a control that kept drawing
+      // "near me" beside an applied location would be inviting a person to
+      // re-answer a question they can already see the answer to.
+      geoOffer: state.geo === undefined ? geoOffer : undefined,
 
       // Typing replaces rather than pushes: one history entry per letter
       // would make Back useless, which is the control the spec's acceptance
@@ -200,12 +206,14 @@ export function SearchStateProvider(
       setFilter: (slug, values) => apply(setFilterValues(state, slug, values)),
       setRange: (slug, range) => apply(setRangeValue(state, slug, range)),
       setGeo: (geo) => {
-        // The person has now answered the location question themselves —
-        // including by answering "anywhere". `defaultGeo` does not get to ask
-        // it again.
-        geoSettled.current = true;
         apply(patchSearchState(state, { geo }));
       },
+      acceptGeoOffer: () => {
+        if (geoOffer === undefined || state.geo !== undefined) return;
+        // A PUSH, like any other filter the person applies: Back takes the
+        // narrowing off again, which is the same promise every chip makes.
+        apply(patchSearchState(state, { geo: geoOffer }));
+      },
       // A page size is a preference, not a step through the results.
       setLimit: (limit) => apply(patchSearchState(state, { limit }), { replace: true }),
       clearAll: () => apply(clearFilters(state)),
@@ -213,25 +221,8 @@ export function SearchStateProvider(
         apply(patchSearchState(state, { anchor, direction })),
       patch: (patch) => apply(patchSearchState(state, patch)),
     };
-  }, [parsed, commit]);
-
-  // An effect, not a render-time write: this puts a value in the URL, and a
-  // router asked to navigate during a render is a warning at best and a loop
-  // at worst. It runs after every commit, which is what makes a `defaultGeo`
-  // that arrives on the fourth render — the browser prompt finally answered —
-  // land as reliably as one present on the first.
-  useEffect(() => {
-    if (geoSettled.current) return;
-    if (parsed.state.geo !== undefined) {
-      // The link brought its own place. That settles the question for this
-      // visit even if the host is still resolving one of its own.
-      geoSettled.current = true;
-      return;
-    }
-    if (defaultGeo === undefined) return;
-    geoSettled.current = true;
-    commit(patchSearchState(parsed.state, { geo: defaultGeo }), { replace: true });
-  }, [defaultGeo, parsed.state, commit]);
+  }, [parsed, commit, geoOffer]);
+
 
   return <StateContext.Provider value={bag}>{children}</StateContext.Provider>;
 }

package/src/i18n/es.ts

@@ -127,6 +127,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.geo.radius_km": "A menos de {km} km",
   "search.geo.radius_label": "Radio, km",
   "search.geo.clear": "En cualquier lugar",
+  "search.geo.near_me": "Cerca de mí",
   "search.geo.everywhere": "Buscando en todas partes",
   "search.geo.box": "Dentro del área mostrada",
   "search.geo.chosen_place": "Un lugar elegido en el mapa",

package/src/i18n/keys.ts

@@ -219,6 +219,7 @@ export const SEARCH_I18N_KEYS = {
   geoRadiusKm: "search.geo.radius_km",
   geoRadiusLabel: "search.geo.radius_label",
   geoClear: "search.geo.clear",
+  geoNearMe: "search.geo.near_me",
   /**
    * What `<LocationSummaryLine>` says when NO location is applied.
    *
@@ -449,6 +450,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.limit.from_link": "This link sets its own page size.",
 
   "search.geo.title": "Location",
+  "search.geo.near_me": "Near me",
   "search.geo.radius_km": "Within {km} km",
   "search.geo.radius_label": "Radius, km",
   "search.geo.clear": "Anywhere",

package/src/i18n/ru.ts

@@ -158,6 +158,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.geo.radius_km": "В радиусе {km} км",
   "search.geo.radius_label": "Радиус, км",
   "search.geo.clear": "Везде",
+  "search.geo.near_me": "Рядом со мной",
   "search.geo.everywhere": "Ищем везде",
   "search.geo.box": "В показанной области",
   "search.geo.chosen_place": "Выбранное место на карте",