@stapel/search-react 0.7.0 → 0.9.0

package/src/headless/SearchStateProvider.tsx

@@ -1,4 +1,11 @@
-import { createContext, useCallback, useContext, useMemo } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+} from "react";
 import type { ReactElement, ReactNode } from "react";
 import type {
   SearchGeo,
@@ -74,6 +81,41 @@ 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).
+   *
+   * 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.
+   *
+   * So the rules, all four of which are about not overruling a person:
+   *
+   *  - **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.
+   *
+   * 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.
+   */
+  readonly defaultGeo?: SearchGeo | undefined;
   readonly children: ReactNode;
 }
 
@@ -86,7 +128,7 @@ export interface SearchStateProviderProps extends ParseSearchStateOptions {
 export function SearchStateProvider(
   props: SearchStateProviderProps
 ): ReactElement {
-  const { adapter, children, ...parseOptions } = props;
+  const { adapter, children, defaultGeo, ...parseOptions } = props;
   const { params, setParams } = adapter;
 
   // The parse options are spread into a stable dependency: a host that builds
@@ -123,6 +165,17 @@ 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;
     const apply = (
@@ -146,7 +199,13 @@ export function SearchStateProvider(
       toggleFilter: (slug, value) => apply(toggleFilterValue(state, slug, value)),
       setFilter: (slug, values) => apply(setFilterValues(state, slug, values)),
       setRange: (slug, range) => apply(setRangeValue(state, slug, range)),
-      setGeo: (geo) => apply(patchSearchState(state, { geo })),
+      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 }));
+      },
       // A page size is a preference, not a step through the results.
       setLimit: (limit) => apply(patchSearchState(state, { limit }), { replace: true }),
       clearAll: () => apply(clearFilters(state)),
@@ -156,6 +215,24 @@ export function SearchStateProvider(
     };
   }, [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]);
+
   return <StateContext.Provider value={bag}>{children}</StateContext.Provider>;
 }
 

package/src/i18n/es.ts

@@ -55,6 +55,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.sort.distance": "Más cercanos",
   "search.sort.server_chose": "Ordenado por {sort}",
 
+  "search.view.label": "Vista",
+  "search.view.list": "Lista",
+  "search.view.grid": "Cuadrícula",
+
   "search.facets.title": "Filtros",
   "search.facets.loading": "Cargando filtros…",
   "search.facets.load_failed": "No pudimos cargar los filtros.",
@@ -74,6 +78,8 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.range_clear": "Quitar",
   "search.facets.range_from_aria": "{feature}, desde",
   "search.facets.range_to_aria": "{feature}, hasta",
+  "search.facets.show_all": "Ver todos ({count})",
+  "search.facets.show_less": "Ver menos",
   "search.facets.range_invalid":
     "«Desde» es mayor que «hasta», así que nada podría coincidir. Intercámbialos para aplicar el rango.",
 
@@ -84,6 +90,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.filters.show_count_at_least.one": "Ver {count}+ resultado",
   "search.filters.show_count_at_least.other": "Ver {count}+ resultados",
   "search.filters.dismiss": "Cerrar los filtros",
+  "search.filters.chips_label": "Filtros",
+  "search.filters.all": "Todos los filtros",
+  "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Categoría",
   "search.category.clear": "Buscar en todo el catálogo",
@@ -101,7 +110,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.geo.radius_label": "Radio, km",
   "search.geo.clear": "En cualquier lugar",
   "search.geo.box": "Dentro del área mostrada",
-  "search.geo.center": "Cerca de {lat}, {lon}",
+  "search.geo.chosen_place": "Un lugar elegido en el mapa",
 
   "search.url.issues_title": "Parte de este enlace no se pudo leer",
   "search.url.issue.not_a_number":

package/src/i18n/keys.ts

@@ -74,6 +74,13 @@ export const SEARCH_I18N_KEYS = {
   sortDistance: "search.sort.distance",
   sortServerChose: "search.sort.server_chose",
 
+  // ── how the results are ARRANGED (see ViewSwitch) ────────────────────────
+  /** The switch's own accessible name — a `Segmented` renders a radiogroup
+   * with no `<label for>` to name it. */
+  viewLabel: "search.view.label",
+  viewList: "search.view.list",
+  viewGrid: "search.view.grid",
+
   // ── facets ───────────────────────────────────────────────────────────────
   facetsTitle: "search.facets.title",
   facetsLoading: "search.facets.loading",
@@ -96,6 +103,12 @@ export const SEARCH_I18N_KEYS = {
   facetsRangeToAria: "search.facets.range_to_aria",
   /** The reason "Apply" is off: the range reads backwards. */
   facetsRangeInvalid: "search.facets.range_invalid",
+  /** The fold on a long facet group: "Show all (46)". The number is in
+   * brackets and not a counted noun, so this is one message and not a plural
+   * family — "(1)" never renders, because a group is only folded when the
+   * tail is longer than one row. */
+  facetsShowAll: "search.facets.show_all",
+  facetsShowLess: "search.facets.show_less",
 
   // ── the filter panel as a whole (phone sheet + host slots) ───────────────
   filtersOpen: "search.filters.open",
@@ -107,6 +120,15 @@ export const SEARCH_I18N_KEYS = {
   /** "Show N+ results" — a FLOOR on the same button. A PLURAL FAMILY. */
   filtersShowCountAtLeast: "search.filters.show_count_at_least",
   filtersDismiss: "search.filters.dismiss",
+  /** The accessible name of the phone chip ROW — a `role="group"` holding a
+   * dozen buttons is announced as nothing at all without one. */
+  filtersChipsLabel: "search.filters.chips_label",
+  /** The leading, icon-only chip: the whole panel. Icon-only means the name
+   * exists ONLY here, so this key is the control's entire accessibility. */
+  filtersAll: "search.filters.all",
+  /** A chip filtering on more than one value: "Bosch, +2". Not a plural
+   * family — nothing is being counted in words. */
+  filtersChipMore: "search.filters.chip_more",
 
   // ── category (a host slot, plus the control that removes it) ─────────────
   categoryTitle: "search.category.title",
@@ -130,7 +152,18 @@ export const SEARCH_I18N_KEYS = {
   geoRadiusLabel: "search.geo.radius_label",
   geoClear: "search.geo.clear",
   geoBox: "search.geo.box",
-  geoCenter: "search.geo.center",
+  /**
+   * What a location constraint is called when nobody has given it a NAME.
+   *
+   * It replaces `search.geo.center` ("Around {lat}, {lon}"), which printed the
+   * two numbers the URL happens to store — `55.756, 37.617` — to a person who
+   * chose a place. A coordinate is storage, not a description: it cannot be
+   * checked by the one reader who could check an address, so a wrong point
+   * reads as authoritative and a right one reads as machinery. Hosts that HAVE
+   * the name (the geocoder that resolved it, the IP guess's city) pass
+   * `geoLabel` and this sentence never appears.
+   */
+  geoChosenPlace: "search.geo.chosen_place",
 
   // ── the URL that could not be read ───────────────────────────────────────
   urlIssuesTitle: "search.url.issues_title",
@@ -239,6 +272,10 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.sort.distance": "Nearest first",
   "search.sort.server_chose": "Sorted by {sort}",
 
+  "search.view.label": "View",
+  "search.view.list": "List",
+  "search.view.grid": "Grid",
+
   "search.facets.title": "Filters",
   "search.facets.loading": "Loading filters…",
   "search.facets.load_failed": "We could not load the filters",
@@ -258,6 +295,8 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.range_clear": "Clear",
   "search.facets.range_from_aria": "{feature}, from",
   "search.facets.range_to_aria": "{feature}, up to",
+  "search.facets.show_all": "Show all ({count})",
+  "search.facets.show_less": "Show fewer",
   "search.facets.range_invalid":
     "“From” is larger than “to”, so nothing could match. Swap them to apply this range.",
 
@@ -268,6 +307,9 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.filters.show_count_at_least.one": "Show {count}+ result",
   "search.filters.show_count_at_least.other": "Show {count}+ results",
   "search.filters.dismiss": "Close the filters",
+  "search.filters.chips_label": "Filters",
+  "search.filters.all": "All filters",
+  "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Category",
   "search.category.clear": "Search the whole catalogue",
@@ -285,7 +327,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.geo.radius_label": "Radius, km",
   "search.geo.clear": "Anywhere",
   "search.geo.box": "Inside the shown area",
-  "search.geo.center": "Around {lat}, {lon}",
+  "search.geo.chosen_place": "A chosen place on the map",
 
   "search.url.issues_title": "Part of this link could not be read",
   "search.url.issue.not_a_number": "“{param}” in this link is not a number, so it was ignored",

package/src/i18n/ru.ts

@@ -78,6 +78,10 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.sort.distance": "Сначала ближние",
   "search.sort.server_chose": "Отсортировано: {sort}",
 
+  "search.view.label": "Вид",
+  "search.view.list": "Списком",
+  "search.view.grid": "Плиткой",
+
   "search.facets.title": "Фильтры",
   "search.facets.loading": "Загружаем фильтры…",
   "search.facets.load_failed": "Не удалось загрузить фильтры.",
@@ -97,6 +101,8 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.range_clear": "Сбросить",
   "search.facets.range_from_aria": "{feature}, от",
   "search.facets.range_to_aria": "{feature}, до",
+  "search.facets.show_all": "Показать все ({count})",
+  "search.facets.show_less": "Свернуть",
   "search.facets.range_invalid":
     "«От» больше, чем «до», — под такой диапазон ничего не подойдёт. Поменяйте значения местами.",
 
@@ -111,6 +117,9 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.filters.show_count_at_least.many": "Показать {count}+ объявлений",
   "search.filters.show_count_at_least.other": "Показать {count}+ объявления",
   "search.filters.dismiss": "Закрыть фильтры",
+  "search.filters.chips_label": "Фильтры",
+  "search.filters.all": "Все фильтры",
+  "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Категория",
   "search.category.clear": "Искать по всему каталогу",
@@ -128,7 +137,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.geo.radius_label": "Радиус, км",
   "search.geo.clear": "Везде",
   "search.geo.box": "В показанной области",
-  "search.geo.center": "Рядом с {lat}, {lon}",
+  "search.geo.chosen_place": "Выбранное место на карте",
 
   "search.url.issues_title": "Часть этой ссылки прочитать не удалось",
   "search.url.issue.not_a_number":