@stapel/search-react 0.18.1 → 0.20.0

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": "Выбранное место на карте",

package/src/state/facets.ts

@@ -147,6 +147,34 @@ export function facetCoverage(group: FacetGroup): number {
   return total;
 }
 
+/**
+ * The order two surfaces put COUNTED facet groups in: what the person has
+ * already answered, then what the corpus has evidence for.
+ *
+ * Stated once, because it was stated twice and the second surface never got
+ * it. The chip row has ranked by coverage since D16; the RAIL rendered
+ * `buildFacetGroups`' output in schema order, and on the deployed phones leaf
+ * that put battery health, four parcel dimensions and two wholesale packing
+ * counts above the brand — so a buyer looking at the category page's 280px
+ * rail saw seven axes of parcel logistics and not one brand (walker D120/D121
+ * on the desktop, D74 on the phone).
+ *
+ * Stable by construction: equal-ranked groups keep the order
+ * `buildFacetGroups` gave them, so a closed set's authored order survives.
+ */
+export function compareFacetsByEvidence(a: FacetGroup, b: FacetGroup): number {
+  const answered = Number(b.selected.length > 0) - Number(a.selected.length > 0);
+  if (answered !== 0) return answered;
+  return facetCoverage(b) - facetCoverage(a);
+}
+
+/** {@link compareFacetsByEvidence}, applied. Never mutates the input. */
+export function orderFacetGroups(
+  groups: readonly FacetGroup[]
+): readonly FacetGroup[] {
+  return [...groups].sort(compareFacetsByEvidence);
+}
+
 export interface BuildFacetGroupsInput {
   /** The envelope's `facets`: `{slug: {value: count}}`. */
   readonly facets: Readonly<Record<string, Readonly<Record<string, number>>>>;

package/src/state/urlState.ts

@@ -444,15 +444,37 @@ export function setRangeValue(
  * would be removing something they never set.
  */
 export function clearFilters(state: SearchQueryState): SearchQueryState {
-  return patchSearchState(state, { filters: {}, ranges: {}, geo: null });
+  // The PLACE survives. It is not a filter (see `activeFilterCount`), it is
+  // not counted by the control that calls this, and a person who chose their
+  // city and then narrowed by price did not ask to be moved back to the whole
+  // country when they widen the price again. The location control has its own
+  // way off, and it says the name of the place it would remove.
+  return patchSearchState(state, { filters: {}, ranges: {} });
 }
 
-/** How many constraints the person has actually applied (facet values +
- * ranges + geo) — what a "clear all (N)" control counts. */
+/**
+ * How many constraints the person has actually applied — facet values and
+ * ranges, and NOTHING ELSE. What a "clear all (N)" control counts.
+ *
+ * ## A latitude is not a filter
+ *
+ * `lat`/`lon` used to add 1 to this, and a place chosen on a map is a real
+ * narrowing, so that looked right. What a person saw was not. On a live board
+ * a landing announced "clear all filters (2)" over an empty page, with two
+ * filters that had no chip, no name and no row in the panel — the owner's
+ * words were "two active filters I can't even look at". A count that names
+ * nothing is worse than no count: it tells a person that something is hiding
+ * their results and gives them nothing to press.
+ *
+ * A coordinate pair is not a filter a person picked, it is the machine form
+ * of a place. The place is stated by the location control, in words, beside
+ * the radius it comes with — its own thing in the chrome, like the search box,
+ * not a row in the filter list and not a number in this sum. So this counts
+ * facets and ranges, and the location says its own name.
+ */
 export function activeFilterCount(state: SearchQueryState): number {
   let count = 0;
   for (const values of Object.values(state.filters)) count += values.length;
   count += Object.keys(state.ranges).length;
-  if (state.geo !== undefined) count += 1;
   return count;
 }