@stapel/search-react 0.9.1 → 0.10.0

package/src/default/FilterChips.tsx

@@ -49,13 +49,12 @@
  */
 import { useState } from "react";
 import type { CSSProperties, ReactElement, ReactNode } from "react";
-import { Button, Flex, Typography } from "antd";
+import { Button } from "antd";
 import { SkinDialog, useDialogSurface } from "@stapel/tokens-antd/skin";
-import { SlotPlaceholder, useT, useTPlural } from "@stapel/core";
+import { useT } from "@stapel/core";
 import { radii, spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import { useFacetPanel } from "../headless/FacetPanel.js";
-import { useAppliedCount } from "../headless/useAppliedCount.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { buildRangeGroups } from "../state/ranges.js";
 import type { FacetGroup } from "../state/facets.js";
@@ -64,6 +63,7 @@ import { FacetGroupControl } from "./FacetGroupControl.js";
 import { RangeFilterRow } from "./RangeFilterRow.js";
 import { geoSummaryFallback } from "./FacetPanelPane.js";
 import type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+import { CHIP_GEO_TEST_IDS, GeoSheet, useApplyLabel } from "./geoSheet.js";
 
 /** The class the scroller carries, for {@link chipRowCss}. */
 export const CHIP_ROW_CLASS = "stapel-filter-chips";
@@ -142,15 +142,14 @@ function chipLabel(group: FacetGroup, t: (key: string, p?: Record<string, unknow
 
 export function FilterChips(props: FilterChipsProps): ReactElement {
   const t = useT();
-  const tPlural = useTPlural();
-  const { state, setGeo } = useSearchState();
+  const { state } = useSearchState();
   const bag = useFacetPanel({
     ...(props.categoryFeatures !== undefined
       ? { categoryFeatures: props.categoryFeatures }
       : {}),
     ...(props.locale !== undefined ? { locale: props.locale } : {}),
   });
-  const applied = useAppliedCount();
+  const applyLabel = useApplyLabel();
   const surface = useDialogSurface();
   const [open, setOpen] = useState<OpenChip>(null);
 
@@ -166,19 +165,6 @@ export function FilterChips(props: FilterChipsProps): ReactElement {
       ? bag.state.data.filter((group) => group.options.length > 0)
       : [];
 
-  // The same sentence the panel's own commit button says, for the same reason:
-  // the results are BEHIND this sheet, so the button that closes it is the
-  // only place a person learns what their choice did.
-  const applyLabel =
-    applied.count === null || applied.kind === "unknown"
-      ? t(SEARCH_I18N_KEYS.filtersApply)
-      : tPlural(
-          applied.kind === "at_least"
-            ? SEARCH_I18N_KEYS.filtersShowCountAtLeast
-            : SEARCH_I18N_KEYS.filtersShowCount,
-          { count: applied.count }
-        );
-
   const close = (): void => {
     setOpen(null);
   };
@@ -338,43 +324,18 @@ export function FilterChips(props: FilterChipsProps): ReactElement {
               );
         })()}
 
-      {open === "geo" &&
-        sheetFor(
-          "geo",
-          t(SEARCH_I18N_KEYS.geoTitle),
-          <Flex vertical gap={spacing[3]}>
-            {/* SETTING a centre needs a geocoder, which is `geo-react`'s and
-                the deployment's. ADJUSTING or CLEARING one the URL already
-                carries does not — which is why the chip still opens on a
-                shared link with no slot filled, and why the absence of the
-                slot is NAMED in development rather than left as a gap under
-                the sheet's title. */}
-            {props.renderGeoFilter?.({
-              value: geo,
-              onChange: (next) => {
-                setGeo(next);
-              },
-            }) ?? <SlotPlaceholder name="renderGeoFilter" data-testid="search-chip-geo-slot" />}
-            {geo !== undefined && (
-              <>
-                <Typography.Text type="secondary" data-testid="search-chip-geo-summary">
-                  {geoChipLabel}
-                </Typography.Text>
-                <Button
-                  style={{ alignSelf: "flex-start" }}
-                  data-testid="search-chip-geo-clear"
-                  data-analytics="none"
-                  data-analytics-reason="a filter is a read, not a flow step"
-                  onClick={() => {
-                    setGeo(null);
-                  }}
-                >
-                  {t(SEARCH_I18N_KEYS.geoClear)}
-                </Button>
-              </>
-            )}
-          </Flex>
-        )}
+      {/* The LOCATION sheet is shared with `<LocationSummaryLine>` — the ref
+          puts a location control on both rows, and they must land in the same
+          place. See `geoSheet.tsx`. */}
+      <GeoSheet
+        open={open === "geo"}
+        onClose={close}
+        testIds={CHIP_GEO_TEST_IDS}
+        {...(props.renderGeoFilter !== undefined
+          ? { renderGeoFilter: props.renderGeoFilter }
+          : {})}
+        {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+      />
     </>
   );
 }

package/src/default/LocationSummaryLine.tsx

@@ -0,0 +1,187 @@
+/**
+ * `<LocationSummaryLine>` — the row above a phone SERP's chips: WHERE this
+ * search is looking on the left, and how much has been narrowed on the right.
+ *
+ * ## Why the location gets a line of its own, above the chips
+ *
+ * It is already a chip (`<FilterChips>` draws one), and on the refs it is a
+ * ROW as well, and that is not redundancy. A chip row scrolls: the geo chip is
+ * one of eight and it is off screen the moment somebody has scrolled to
+ * "Year". Location is the one constraint on a classified that changes what a
+ * result MEANS rather than narrowing a set — "1 200 €" is a different offer in
+ * the next city — so it is the one that must be readable without scrolling
+ * anything. The two controls open the same sheet (`geoSheet.tsx`), so tapping
+ * either lands in the same place.
+ *
+ * ## Never a coordinate
+ *
+ * This pair holds a `lat` and a `lon` and has no way on earth to turn them
+ * into "Berlin Mitte" — that is a geocoder, and a search package that grew one
+ * to say a nicer sentence would have taken on the whole of `geo-react`. So the
+ * line says the name it was HANDED (`geoLabel`), or that a place is chosen,
+ * and adds the radius, which is a number this pair does own. With nothing
+ * applied it says the search is looking everywhere, which is the truth and is
+ * also the invitation to narrow it.
+ *
+ * ## 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
+ * number nobody reads, so it shows a dot. This is a full-width row with a word
+ * on it, so the badge has room to say HOW MANY constraints are applied — which
+ * is the difference between "something is filtered" and "four things are, and
+ * that is why there are three results". Both read the same
+ * `activeFilters` off the URL state; neither invents a second counter.
+ */
+import { useState } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Badge, Button, Flex } from "antd";
+import { useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { geoSummaryFallback } from "./FacetPanelPane.js";
+import type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+import { GeoSheet, SUMMARY_GEO_TEST_IDS } from "./geoSheet.js";
+
+/** The row. Both ends are text buttons, so the row reads as a line of type
+ * rather than as two controls bolted onto a results page. */
+const ROW: CSSProperties = { width: "100%" };
+
+/** Each end shrinks before it wraps; the location is the half that may
+ * ellipsis, because a long place name must not push "Filters" off screen. */
+const LOCATION: CSSProperties = {
+  minWidth: 0,
+  paddingInline: 0,
+  textAlign: "start",
+};
+
+export interface LocationSummaryLineProps {
+  /**
+   * The location control the sheet opens onto — the same slot the panel and
+   * the chip row take. Without it the sheet still opens (a location the URL
+   * already carries can be widened and cleared with no geocoder), and the
+   * absence is NAMED in development rather than left as a blank sheet.
+   */
+  readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
+  /**
+   * What the current place is CALLED. See the file header: this pair prints
+   * the name it is handed or admits it does not know one, never the numbers.
+   */
+  readonly geoLabel?: ReactNode;
+  /**
+   * Open the whole filter panel — the same contract `<FilterChips.onOpenAll>`
+   * states, and conventionally the same callback: the SURFACE owns that sheet
+   * because the surface is what it covers.
+   */
+  readonly onOpenAll: () => void;
+}
+
+/** A map pin in `currentColor` — the house convention: an inline monochrome
+ * SVG, no icon-font dependency, and it inherits the theme rather than carrying
+ * a colour. `aria-hidden` because the text beside it is the name. */
+function PinGlyph(): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-hidden="true"
+    >
+      <path d="M12 21s7-5.6 7-11a7 7 0 1 0-14 0c0 5.4 7 11 7 11z" />
+      <circle cx="12" cy="10" r="2.6" />
+    </svg>
+  );
+}
+
+export function LocationSummaryLine(
+  props: LocationSummaryLineProps
+): ReactElement {
+  const t = useT();
+  const { state, activeFilters } = useSearchState();
+  const [open, setOpen] = useState(false);
+  const geo = state.geo;
+
+  // The radius is a NUMBER this pair owns (`radius_km` in the URL), so unlike
+  // the place's name it can be stated without asking anyone. A bbox has no
+  // radius to state; a centre without one is "around here" and says nothing
+  // rather than inventing a default the server never applied.
+  const radius =
+    geo !== undefined && geo.kind === "center" && geo.radiusKm !== undefined
+      ? t(SEARCH_I18N_KEYS.geoRadiusKm, { km: geo.radiusKm })
+      : undefined;
+
+  const where: ReactNode =
+    geo === undefined
+      ? t(SEARCH_I18N_KEYS.geoEverywhere)
+      : (props.geoLabel ?? geoSummaryFallback(geo, t));
+
+  return (
+    <>
+      <Flex
+        align="center"
+        justify="space-between"
+        gap={spacing[2]}
+        style={ROW}
+        data-testid="search-location-summary"
+        data-geo={geo === undefined ? "off" : "on"}
+      >
+        <Button
+          type="link"
+          style={LOCATION}
+          icon={<PinGlyph />}
+          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>
+          )}
+        </Button>
+
+        {/* The count, not a dot: this row has the width to say how many. */}
+        <Badge
+          count={activeFilters}
+          size="small"
+          data-testid="search-location-filters-badge"
+        >
+          <Button
+            type="link"
+            style={{ paddingInline: 0 }}
+            data-testid="search-location-filters"
+            data-active={activeFilters > 0 ? "true" : "false"}
+            data-analytics="none"
+            data-analytics-reason="opening the filter sheet is a read, not a flow step"
+            onClick={props.onOpenAll}
+          >
+            {t(SEARCH_I18N_KEYS.filtersAll)}
+          </Button>
+        </Badge>
+      </Flex>
+
+      <GeoSheet
+        open={open}
+        onClose={() => {
+          setOpen(false);
+        }}
+        testIds={SUMMARY_GEO_TEST_IDS}
+        {...(props.renderGeoFilter !== undefined
+          ? { renderGeoFilter: props.renderGeoFilter }
+          : {})}
+        {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+      />
+    </>
+  );
+}

package/src/default/SearchPage.tsx

@@ -12,9 +12,9 @@
  * The seams a storefront fills: `renderCard` (a `<ListingCard>`),
  * `categoryFeatures` (from categories-react, for facet labels and range rows),
  * `renderCategoryFilter` / `renderGeoFilter` (controls other pairs own),
- * `footer` (the container's own chrome), `filtersHeader` and `resultsHeading`.
- * None of them is optional behaviour in disguise — every one has a working
- * default or a visible placeholder.
+ * `footer` (the container's own chrome), `filtersHeader`, `resultsHeader` and
+ * `resultsHeading`. None of them is optional behaviour in disguise — every one
+ * has a working default or a visible placeholder.
  *
  * ── The screen could not start a search ───────────────────────────────────
  *
@@ -185,6 +185,25 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * sense that matters and not a decoration bolted on top.
    */
   readonly filtersHeader?: ReactNode;
+  /**
+   * The row ABOVE the chips and the results — where `<LocationSummaryLine>`
+   * goes on the phone SERP.
+   *
+   * A NEW slot rather than a reuse, and the existing four were each checked
+   * first: `filtersHeader` is inside the filter panel (it is a filter, and on
+   * a phone it is behind the sheet, which is precisely where a location
+   * summary must NOT be); `breadcrumb` renders in the right place but names a
+   * walk up the CATEGORY tree, and a host wanting a trail AND a location row
+   * would have to choose; `resultsHeading` and the pane's `toolbar` are inside
+   * the results pane, below the chips. Nothing sat between "the search box"
+   * and "the filters", and that gap is exactly the ref's location row.
+   *
+   * It is rendered in the page's vertical stack, so it spans the full width in
+   * BOTH layouts — above the chip row on a phone, above the two columns on a
+   * desktop. That is deliberate: whatever states where a search is looking
+   * describes the whole page, not the results column of it.
+   */
+  readonly resultsHeader?: ReactNode;
   /** What this surface calls its result list. See
    * {@link SearchResultsPaneProps.heading}. */
   readonly resultsHeading?: ReactNode;
@@ -261,6 +280,7 @@ interface SearchPageBodyProps {
   readonly geoLabel?: ReactNode;
   readonly footer?: ReactNode;
   readonly filtersHeader?: ReactNode;
+  readonly resultsHeader?: ReactNode;
   readonly resultsHeading?: ReactNode;
   readonly degradationNotice?: DegradationNoticeVariant;
   readonly filtersLayout?: SearchFiltersLayout;
@@ -414,6 +434,14 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       )}
       <UrlIssueNotice />
 
+      {/* 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
+          about location says nothing rather than reserving a blank row. */}
+      {props.resultsHeader !== undefined && (
+        <div data-testid="search-results-header">{props.resultsHeader}</div>
+      )}
+
       {showFilters && layout === "sheet" ? (
         <>
           {/* The phone's filter row. It REPLACES the full-width "Filters (3)"
@@ -492,6 +520,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     defaultGeo,
     footer,
     filtersHeader,
+    resultsHeader,
     resultsHeading,
     degradationNotice,
     filtersLayout,
@@ -521,6 +550,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(geoLabel !== undefined ? { geoLabel } : {})}
           {...(footer !== undefined ? { footer } : {})}
           {...(filtersHeader !== undefined ? { filtersHeader } : {})}
+          {...(resultsHeader !== undefined ? { resultsHeader } : {})}
           {...(resultsHeading !== undefined ? { resultsHeading } : {})}
           {...(degradationNotice !== undefined ? { degradationNotice } : {})}
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}

package/src/default/geoSheet.tsx

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ *
+ * ── What the sheet can do without a geocoder, and what it cannot ───────────
+ *
+ * SETTING a centre needs a map and a place-name lookup, which belong to
+ * `geo-react` and to the deployment: that is `renderGeoFilter`, and when it is
+ * unfilled the gap is NAMED (`SlotPlaceholder`) rather than left as a blank
+ * area under the sheet's title. ADJUSTING or CLEARING a location the URL
+ * already carries needs neither — `lat`/`lon`/`radius_km` are numbers this
+ * pair owns — which is why the sheet still opens usefully on a shared link
+ * with no slot wired.
+ *
+ * NAMING the place is a third thing and it is the host's: this package holds
+ * two coordinates and has no way to turn them into "Berlin Mitte", so it
+ * prints the name it was handed (`geoLabel`) or says that a place is chosen —
+ * never the numbers. `test/geo.test.tsx` asserts no digit of the point reaches
+ * the DOM, on either surface.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import { SkinDialog } from "@stapel/tokens-antd/skin";
+import { SlotPlaceholder, useT, useTPlural } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { useAppliedCount } from "../headless/useAppliedCount.js";
+import { useSearchState } from "../headless/SearchStateProvider.js";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { geoSummaryFallback } from "./FacetPanelPane.js";
+import type { GeoFilterSlotProps } from "./FacetPanelPane.js";
+
+/** The test ids a surface gives its own copy of the sheet — the chip row and
+ * the summary line each keep the names their tests already know. */
+export interface GeoSheetTestIds {
+  readonly sheet: string;
+  readonly apply: string;
+  readonly slot: string;
+  readonly summary: string;
+  readonly clear: string;
+}
+
+/** The chip row's door. These names predate the split and are what
+ * `test/geo.test.tsx` already asks for, so they travel with the sheet rather
+ * than being renamed by a refactor nobody asked to observe. */
+export const CHIP_GEO_TEST_IDS: GeoSheetTestIds = {
+  sheet: "filter-chip-sheet-geo",
+  apply: "filter-chip-apply-geo",
+  slot: "search-chip-geo-slot",
+  summary: "search-chip-geo-summary",
+  clear: "search-chip-geo-clear",
+};
+
+/** The summary line's door — a different set, so a page holding both rows
+ * never hands a test two elements under one name. */
+export const SUMMARY_GEO_TEST_IDS: GeoSheetTestIds = {
+  sheet: "search-location-sheet",
+  apply: "search-location-apply",
+  slot: "search-location-slot",
+  summary: "search-location-sheet-summary",
+  clear: "search-location-clear",
+};
+
+export interface GeoSheetProps {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
+  readonly geoLabel?: ReactNode;
+  readonly testIds: GeoSheetTestIds;
+}
+
+/**
+ * "Show 25 results", not "Show results".
+ *
+ * The results are BEHIND this sheet, so the button that closes it is the only
+ * place a person learns what their choice did. When the engine cannot say how
+ * many there are it says nothing rather than a number it made up.
+ */
+export function useApplyLabel(): string {
+  const t = useT();
+  const tPlural = useTPlural();
+  const applied = useAppliedCount();
+  return applied.count === null || applied.kind === "unknown"
+    ? t(SEARCH_I18N_KEYS.filtersApply)
+    : tPlural(
+        applied.kind === "at_least"
+          ? SEARCH_I18N_KEYS.filtersShowCountAtLeast
+          : SEARCH_I18N_KEYS.filtersShowCount,
+        { count: applied.count }
+      );
+}
+
+export function GeoSheet(props: GeoSheetProps): ReactElement {
+  const t = useT();
+  const { state, setGeo } = useSearchState();
+  const applyLabel = useApplyLabel();
+  const geo = state.geo;
+  const summary: ReactNode =
+    geo === undefined
+      ? null
+      : (props.geoLabel ?? geoSummaryFallback(geo, t));
+
+  return (
+    <SkinDialog
+      open={props.open}
+      onClose={props.onClose}
+      title={t(SEARCH_I18N_KEYS.geoTitle)}
+      dismissLabel={t(SEARCH_I18N_KEYS.filtersDismiss)}
+      data-testid={props.testIds.sheet}
+      footer={
+        <Button
+          block
+          type="primary"
+          data-testid={props.testIds.apply}
+          data-analytics="none"
+          data-analytics-reason="the filter is already applied; this closes the sheet"
+          onClick={props.onClose}
+        >
+          {applyLabel}
+        </Button>
+      }
+    >
+      <Flex vertical gap={spacing[3]}>
+        {props.renderGeoFilter?.({
+          value: geo,
+          onChange: (next) => {
+            setGeo(next);
+          },
+        }) ?? (
+          <SlotPlaceholder
+            name="renderGeoFilter"
+            data-testid={props.testIds.slot}
+          />
+        )}
+        {geo !== undefined && (
+          <>
+            <Typography.Text type="secondary" data-testid={props.testIds.summary}>
+              {summary}
+            </Typography.Text>
+            <Button
+              style={{ alignSelf: "flex-start" }}
+              data-testid={props.testIds.clear}
+              data-analytics="none"
+              data-analytics-reason="a filter is a read, not a flow step"
+              onClick={() => {
+                setGeo(null);
+              }}
+            >
+              {t(SEARCH_I18N_KEYS.geoClear)}
+            </Button>
+          </>
+        )}
+      </Flex>
+    </SkinDialog>
+  );
+}

package/src/default/index.ts

@@ -51,6 +51,9 @@ export type {
 export { FilterChips, CHIP_ROW_CLASS, CHIP_ROW_STYLE_HREF, chipRowCss } from "./FilterChips.js";
 export type { FilterChipsProps } from "./FilterChips.js";
 
+export { LocationSummaryLine } from "./LocationSummaryLine.js";
+export type { LocationSummaryLineProps } from "./LocationSummaryLine.js";
+
 export {
   FacetGroupControl,
   facetGroupShape,