@stapel/search-react 0.4.0 → 0.8.0

package/src/default/SortSelect.tsx

@@ -10,24 +10,29 @@
  *
  * `sort=distance` needs a centre — the server answers
  * `error.400.search_sort_needs_center` without one. The option is therefore
- * DISABLED with the reason named when no geo centre is set, rather than
- * offered and then refused.
+ * DISABLED when no geo centre is set, and the REASON is rendered beside the
+ * control through `GatedControl`, not in a `title=` a phone can never surface.
+ * That is the whole defect this file used to carry: the one sort a person
+ * would most want on a phone was greyed out with its explanation in a hover.
  */
 import type { ReactElement } from "react";
 import { Flex, Select, Typography } from "antd";
-import { useT } from "@stapel/core";
+import { actionAvailable, actionBlocked, useT } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import { GatedControl } from "@stapel/tokens-antd/skin";
+import { spacing } from "@stapel/tokens";
 import { SEARCH_SORTS } from "../api/types.js";
 import { useAppliedSort } from "../headless/useAppliedSort.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import { sortLabelKey } from "./sortLabels.js";
 
-const SORT_LABEL_KEY: Readonly<Record<string, string>> = {
-  relevance: SEARCH_I18N_KEYS.sortRelevance,
-  newest: SEARCH_I18N_KEYS.sortNewest,
-  price_asc: SEARCH_I18N_KEYS.sortPriceAsc,
-  price_desc: SEARCH_I18N_KEYS.sortPriceDesc,
-  distance: SEARCH_I18N_KEYS.sortDistance,
-};
+/**
+ * The select's floor width. Off the spacing scale on purpose and named for it:
+ * it is the width of the longest shipped sort label ("Price: low to high") at
+ * the default type step, so the control does not resize as the choice changes.
+ */
+export const SORT_SELECT_MIN_WIDTH = 200;
 
 export interface SortSelectProps {
   /** The sort the SERVER applied, shown when the URL names none. Omitted, it
@@ -54,33 +59,41 @@ export function SortSelect(props: SortSelectProps): ReactElement {
       ? [...SEARCH_SORTS, active]
       : SEARCH_SORTS;
 
+  // The gate is about ONE option, not the whole control — so the binding's
+  // `aria-describedby` is spread onto the select (a screen reader hears the
+  // reason with the control) and its `disabled` deliberately is not: the other
+  // four sorts work perfectly well without a location.
+  const distance: ActionAvailability = hasCentre
+    ? actionAvailable()
+    : actionBlocked("error.400.search_sort_needs_center");
+
   return (
-    <Flex gap={8} align="center">
-      <Typography.Text type="secondary">
-        {t(SEARCH_I18N_KEYS.sortLabel)}
-      </Typography.Text>
-      <Select<string>
-        data-testid="search-sort"
-        style={{ minWidth: 180 }}
-        value={active ?? null}
-        onChange={(next) => {
-          setSort(next);
-        }}
-        options={values.map((value) => {
-          const key = SORT_LABEL_KEY[value];
-          const needsCentre = value === "distance" && !hasCentre;
-          return {
-            value,
-            label: key !== undefined ? t(key) : value,
-            disabled: needsCentre,
-            // A disabled control states its reason (the ActionAvailability
-            // canon), even inside a select.
-            ...(needsCentre
-              ? { title: t("error.400.search_sort_needs_center") }
-              : {}),
-          };
-        })}
-      />
-    </Flex>
+    <GatedControl gate={distance} testId="search-sort-gate">
+      {(bind) => (
+        <Flex gap={spacing[2]} align="center">
+          <Typography.Text type="secondary" aria-hidden="true">
+            {t(SEARCH_I18N_KEYS.sortLabel)}
+          </Typography.Text>
+          <Select<string>
+            data-testid="search-sort"
+            aria-label={t(SEARCH_I18N_KEYS.sortLabel)}
+            aria-describedby={bind["aria-describedby"]}
+            style={{ minWidth: SORT_SELECT_MIN_WIDTH }}
+            value={active ?? null}
+            onChange={(next) => {
+              setSort(next);
+            }}
+            options={values.map((value) => {
+              const key = sortLabelKey(value);
+              return {
+                value,
+                label: key !== undefined ? t(key) : value,
+                disabled: value === "distance" && !hasCentre,
+              };
+            })}
+          />
+        </Flex>
+      )}
+    </GatedControl>
   );
 }

package/src/default/UrlIssueNotice.tsx

@@ -9,10 +9,28 @@
  */
 import type { ReactElement } from "react";
 import { Alert } from "antd";
+import { spacing } from "@stapel/tokens";
 import { useT } from "@stapel/core";
+import { FILTER_PREFIX, RANGE_PREFIX } from "../state/urlState.js";
 import { useSearchState } from "../headless/SearchStateProvider.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
+/**
+ * The parameter as a person can recognise it.
+ *
+ * The codec reports the WIRE name, which for a facet or a range carries the
+ * prefix that tells the backend which family it belongs to (`r.price`,
+ * `f.brand`). That prefix is a protocol detail: the sentence is read by
+ * somebody who followed a link, and "price" is the part of `r.price` they
+ * have any chance of recognising.
+ */
+function readableParam(param: string): string {
+  for (const prefix of [RANGE_PREFIX, FILTER_PREFIX]) {
+    if (param.startsWith(prefix)) return param.slice(prefix.length);
+  }
+  return param;
+}
+
 export function UrlIssueNotice(): ReactElement | null {
   const t = useT();
   const { issues } = useSearchState();
@@ -22,12 +40,12 @@ export function UrlIssueNotice(): ReactElement | null {
       type="warning"
       showIcon
       data-testid="search-url-issues"
-      message={t(SEARCH_I18N_KEYS.urlIssuesTitle)}
+      title={t(SEARCH_I18N_KEYS.urlIssuesTitle)}
       description={
-        <ul style={{ margin: 0, paddingInlineStart: 20 }}>
+        <ul style={{ margin: 0, paddingInlineStart: spacing[5] }}>
           {issues.map((issue) => (
             <li key={`${issue.param}:${issue.code}`}>
-              {t(issue.messageKey, { param: issue.param })}
+              {t(issue.messageKey, { param: readableParam(issue.param) })}
             </li>
           ))}
         </ul>

package/src/default/ViewSwitch.tsx

@@ -0,0 +1,147 @@
+/**
+ * `<ViewSwitch>` — how the results are ARRANGED: a list, a grid, or something
+ * the deployment brought with it.
+ *
+ * ## Why two of the three views ship and the third is a slot
+ *
+ * A list and a grid are the SAME data in two arrangements: one column of wide
+ * rows, or as many card columns as fit. That is a layout decision and a search
+ * pair can take it. A MAP is not — it needs a tile source, a projection, a
+ * marker layer and a geocoder, all of which live in `geo-react` and none of
+ * which a search package may depend on. So the third view arrives as a
+ * {@link SearchView} the host declares, with its own `render`, and this
+ * component treats it exactly like the two it ships. A pair that hardcoded a
+ * "map" button and then had nothing to draw would be offering a control that
+ * cannot work — the defect class the fleet calls a silent slot.
+ *
+ * ## The view is not URL state, and that is deliberate
+ *
+ * `sort`, `page size`, every filter and the cursor are in the query string,
+ * because they change WHAT the answer is and a shared link has to carry them.
+ * The view changes only how the same answer is drawn. Putting it in the URL
+ * would make every arrangement flip a new history entry and would rewrite the
+ * meaning of a link somebody sent. The page holds it in component state and
+ * offers `defaultView`/`onViewChange` so a host that wants it remembered can
+ * persist it wherever it keeps preferences.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Segmented } from "antd";
+import { useT } from "@stapel/core";
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+import type { SearchResultsRenderer } from "./SearchResultsPane.js";
+
+/** How the pane's own arrangements lay a page of results out. */
+export type SearchResultsLayout = "grid" | "list";
+
+/** One arrangement offered by the switch. */
+export interface SearchView {
+  /** Stable id — what `defaultView`/`onViewChange` speak in. */
+  readonly id: string;
+  /** i18n KEY for the view's name (never a literal: the switch is chrome). */
+  readonly labelKey: string;
+  /** The glyph beside the name. Omitted, the name stands alone. */
+  readonly icon?: ReactNode;
+  /**
+   * One of the pane's own arrangements. Ignored when {@link SearchView.render}
+   * is present, which replaces the arrangement entirely.
+   */
+  readonly layout?: SearchResultsLayout;
+  /**
+   * The whole result surface, for a view the pair cannot draw — a map, a
+   * comparison table. It receives the loaded rows; the pane keeps its four
+   * load arms around it, so "nothing found" and "we could not run this search"
+   * stay the pane's sentences rather than the slot's problem.
+   */
+  readonly render?: SearchResultsRenderer;
+}
+
+/** Rows — one wide row per result, the arrangement a scan reads fastest. */
+function ListGlyph(): ReactElement {
+  return (
+    <ViewGlyph>
+      <path d="M4 6.5h16M4 12h16M4 17.5h16" />
+    </ViewGlyph>
+  );
+}
+
+/** Cards — as many columns as fit. */
+function GridGlyph(): ReactElement {
+  return (
+    <ViewGlyph>
+      <rect x="4" y="4" width="7" height="7" rx="1.5" />
+      <rect x="13" y="4" width="7" height="7" rx="1.5" />
+      <rect x="4" y="13" width="7" height="7" rx="1.5" />
+      <rect x="13" y="13" width="7" height="7" rx="1.5" />
+    </ViewGlyph>
+  );
+}
+
+function ViewGlyph(props: { readonly children: ReactNode }): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      role="img"
+      aria-hidden="true"
+    >
+      {props.children}
+    </svg>
+  );
+}
+
+/** The two arrangements the pair itself can draw. */
+export const SEARCH_BUILTIN_VIEWS: readonly SearchView[] = [
+  {
+    id: "list",
+    labelKey: SEARCH_I18N_KEYS.viewList,
+    icon: <ListGlyph />,
+    layout: "list",
+  },
+  {
+    id: "grid",
+    labelKey: SEARCH_I18N_KEYS.viewGrid,
+    icon: <GridGlyph />,
+    layout: "grid",
+  },
+];
+
+/** The view `id` currently in force, or the first offered one. */
+export function resolveView(
+  views: readonly SearchView[],
+  id: string | undefined
+): SearchView | undefined {
+  return views.find((view) => view.id === id) ?? views[0];
+}
+
+export interface ViewSwitchProps {
+  readonly views: readonly SearchView[];
+  readonly value: string;
+  readonly onChange: (id: string) => void;
+}
+
+/**
+ * The switch itself. Renders nothing for a single view: a control offering one
+ * choice is not a control, it is a label that can be clicked.
+ */
+export function ViewSwitch(props: ViewSwitchProps): ReactElement | null {
+  const t = useT();
+  if (props.views.length < 2) return null;
+  return (
+    <Segmented<string>
+      aria-label={t(SEARCH_I18N_KEYS.viewLabel)}
+      value={props.value}
+      data-testid="search-view-switch"
+      onChange={props.onChange}
+      options={props.views.map((view) => ({
+        value: view.id,
+        label: t(view.labelKey),
+        ...(view.icon !== undefined ? { icon: view.icon } : {}),
+      }))}
+    />
+  );
+}

package/src/default/index.ts

@@ -6,37 +6,80 @@
  * never pays for this bundle (enforced by size-limit and the bundle-purity
  * test).
  *
- * Three override levers, none of which requires forking anything:
+ * Five override levers, none of which requires forking anything:
  *
  *  1. **`renderCard`** — the card slot. A storefront passes
  *     `<ListingCard>` from `@stapel/listings-react/default`; the generic card
  *     here is the documented default, not the intended end state (spec §3.7).
  *     `renderResults` is the level above it: the whole layout, for a container
  *     whose arrangement is not "cards in a grid".
- *  2. **`categoryFeatures`** — the facet-label slot. The server sends
- *     `{value: count}` and no labels; the schema that names them lives in
- *     categories, and the container hands it in (spec §6.2 item 2).
- *  3. **retheming through the §68 token JSON** — every surface wraps itself
- *     in `<SearchSkinTheme>`, so a host's regenerated `--stapel-*` custom
+ *  2. **`categoryFeatures`** — the facet-label slot, and the source of which
+ *     slugs get a numeric range row. The server sends `{value: count}` and no
+ *     labels; the schema that names them lives in categories, and the
+ *     container hands it in (spec §6.2 item 2).
+ *  3. **`renderCategoryFilter`** — the catalogue picker. `categories-react`
+ *     owns walking the tree; this pair owns the `category` parameter.
+ *  4. **`renderGeoFilter`** — the location control. `geo-react` owns the map
+ *     and the geocoder; this pair owns `lat`/`lon`/`radius_km`/`bbox`, and
+ *     keeps the controls that WIDEN a location a link already carries.
+ *  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.
+ *
+ * The pair's own `theme.tsx` and `ErrorAlert.tsx` are GONE as of 0.6.0: both
+ * were copies of a decision now stated once in `@stapel/tokens-antd/skin`
+ * (`SkinTheme`, `ErrorAlert`). A host that imported `SearchSkinTheme` imports
+ * `SkinTheme` from the substrate instead — same props, one implementation, and
+ * a runtime `data-theme` flip actually repaints it.
  */
 
 // ── surfaces ────────────────────────────────────────────────────────────────
 export { SearchPage } from "./SearchPage.js";
-export type { SearchPageProps } from "./SearchPage.js";
+export type { SearchPageProps, SearchFiltersLayout } from "./SearchPage.js";
 
-export { SearchResultsPane } from "./SearchResultsPane.js";
+export { SearchResultsPane, RESULTS_MAX_WIDTH } from "./SearchResultsPane.js";
 export type {
   SearchResultsPaneProps,
   SearchResultsRenderer,
 } from "./SearchResultsPane.js";
 
+export { FilterChips, CHIP_ROW_CLASS, CHIP_ROW_STYLE_HREF, chipRowCss } from "./FilterChips.js";
+export type { FilterChipsProps } from "./FilterChips.js";
+
+export {
+  FacetGroupControl,
+  facetGroupShape,
+  facetOptionNodes,
+  FACET_VISIBLE_OPTIONS,
+} from "./FacetGroupControl.js";
+export type {
+  FacetGroupControlProps,
+  FacetGroupShape,
+  FacetOptionNode,
+} from "./FacetGroupControl.js";
+
 export { FacetPanelPane } from "./FacetPanelPane.js";
-export type { FacetPanelPaneProps } from "./FacetPanelPane.js";
+export type {
+  FacetPanelPaneProps,
+  CategoryFilterSlotProps,
+  GeoFilterSlotProps,
+} from "./FacetPanelPane.js";
 
-export { RankingDisclosurePane } from "./RankingDisclosurePane.js";
+export { RankingDisclosurePane, RANKING_MAX_WIDTH } from "./RankingDisclosurePane.js";
 export type { RankingDisclosurePaneProps } from "./RankingDisclosurePane.js";
 
+// ── controls, exported so a host can compose its own layout ─────────────────
+export { SearchBox } from "./SearchBox.js";
+export type { SearchBoxProps } from "./SearchBox.js";
+export { SortSelect, SORT_SELECT_MIN_WIDTH } from "./SortSelect.js";
+export type { SortSelectProps } from "./SortSelect.js";
+export { ViewSwitch, SEARCH_BUILTIN_VIEWS, resolveView } from "./ViewSwitch.js";
+export type { ViewSwitchProps, SearchView, SearchResultsLayout } from "./ViewSwitch.js";
+export { PageSizeSelect, SEARCH_PAGE_SIZES } from "./PageSizeSelect.js";
+export type { PageSizeSelectProps } from "./PageSizeSelect.js";
+export { LanguageSelect } from "./LanguageSelect.js";
+export type { LanguageSelectProps } from "./LanguageSelect.js";
+
 // ── parts, exported so a host can compose or wrap one ───────────────────────
 export { SearchResultCard, GENERIC_CARD_FIELDS } from "./SearchResultCard.js";
 export type { SearchCardProps, SearchCardRenderer } from "./SearchResultCard.js";
@@ -46,11 +89,8 @@ export type {
   DegradationNoticeVariant,
 } from "./DegradationNotice.js";
 export { UrlIssueNotice } from "./UrlIssueNotice.js";
-export { SortSelect } from "./SortSelect.js";
-export type { SortSelectProps } from "./SortSelect.js";
-export { ErrorAlert } from "./ErrorAlert.js";
+export { RangeFilterRow } from "./RangeFilterRow.js";
+export type { RangeFilterRowProps } from "./RangeFilterRow.js";
 
 // ── theming ─────────────────────────────────────────────────────────────────
-export { SearchSkinTheme } from "./theme.js";
-export type { SearchSkinThemeProps } from "./theme.js";
 export type { ThemeModeProp } from "./types.js";

package/src/default/sortLabels.ts

@@ -0,0 +1,34 @@
+/**
+ * A sort SLUG as the skin names it, in one place.
+ *
+ * `relevance`, `price_asc`, `distance` are wire values: the URL carries them,
+ * the envelope reports them, and the ranking disclosure lists them per scorer.
+ * The sort SELECT translated them and the disclosure did not, so the same page
+ * offered "Most relevant" in the control and stamped "Applies to: relevance"
+ * under every parameter — the registry's word, in a statutory text, next to
+ * the human word for the same thing.
+ *
+ * A slug the pair does not ship is returned as it is. Deployments register
+ * their own scorers and sorts, and an unknown one is a real value that belongs
+ * on screen; only an invented label would be worse.
+ */
+import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
+
+const SORT_LABEL_KEY: Readonly<Record<string, string>> = {
+  relevance: SEARCH_I18N_KEYS.sortRelevance,
+  newest: SEARCH_I18N_KEYS.sortNewest,
+  price_asc: SEARCH_I18N_KEYS.sortPriceAsc,
+  price_desc: SEARCH_I18N_KEYS.sortPriceDesc,
+  distance: SEARCH_I18N_KEYS.sortDistance,
+};
+
+/** The i18n key for a shipped sort, or `undefined` for a deployment's own. */
+export function sortLabelKey(sort: string): string | undefined {
+  return SORT_LABEL_KEY[sort];
+}
+
+/** The sort's name for a reader, falling back to the slug. */
+export function sortLabel(t: (key: string) => string, sort: string): string {
+  const key = SORT_LABEL_KEY[sort];
+  return key === undefined ? sort : t(key);
+}

package/src/headless/FacetPanel.tsx

@@ -72,6 +72,34 @@ export function FacetPanel(props: {
   enabled?: boolean;
   children: (bag: FacetPanelBag) => ReactNode;
 }): ReactNode {
+  return props.children(
+    useFacetPanel({
+      ...(props.categoryFeatures !== undefined
+        ? { categoryFeatures: props.categoryFeatures }
+        : {}),
+      ...(props.locale !== undefined ? { locale: props.locale } : {}),
+      ...(props.enabled !== undefined ? { enabled: props.enabled } : {}),
+    })
+  );
+}
+
+/**
+ * The same bag, as a hook — for a caller that has to know what the panel WILL
+ * render before it renders it.
+ *
+ * The one real caller is `<SearchPage>`: a facet column is a quarter of a
+ * catalogue page, and on a deployment whose plan has no facets at all it was
+ * a quarter of every results page spent on an empty-state illustration
+ * repeating "no filters for this search". Whether to lay out that column is a
+ * LAYOUT decision, and layout is decided by the component that owns the grid
+ * — which therefore has to be able to ask. A render prop cannot answer a
+ * question asked one level up.
+ */
+export function useFacetPanel(props: {
+  categoryFeatures?: readonly FeatureDef[];
+  locale?: string;
+  enabled?: boolean;
+} = {}): FacetPanelBag {
   const { state: searchState, setFilter, setRange, clearAll, toggleFilter, activeFilters } =
     useSearchState();
   const t = useT();
@@ -96,7 +124,7 @@ export function FacetPanel(props: {
     })
   );
 
-  return props.children({
+  return {
     state: groups,
     approximate: meta.approximate,
     skipped: meta.skipped,
@@ -109,5 +137,5 @@ export function FacetPanel(props: {
       setFilter(slug, []);
     },
     clearAll,
-  });
+  };
 }

package/src/headless/useAppliedCount.ts

@@ -0,0 +1,41 @@
+/**
+ * How many results the page currently in cache holds, and whether that number
+ * may be spoken as a number.
+ *
+ * The same trick as {@link useAppliedSort}: `enabled: false` on the key
+ * `<SearchResults>` populates, so a control that wants to SAY the count
+ * subscribes to the answer already on screen instead of issuing a second
+ * search of its own. A filter sheet whose button reads "Show 25 results" is
+ * the difference between committing to a change and guessing at one, and it
+ * must not cost a request to know that.
+ *
+ * Not exported from the package entry: it is the shape `<SearchPage>` needs to
+ * label one button, and a public hook would be a second, thinner way to ask
+ * what `<SearchResults>` already answers in full.
+ */
+import { useSearchQuery } from "../model/queries.js";
+import { countKind, parseDegradations } from "../state/degradations.js";
+import type { SearchCountKind } from "../state/degradations.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+export interface AppliedCount {
+  /** `null` when the engine cannot say — never rendered as `0`. */
+  readonly count: number | null;
+  readonly kind: SearchCountKind;
+}
+
+export function useAppliedCount(): AppliedCount {
+  const { state } = useSearchState();
+  const query = useSearchQuery(state, { enabled: false });
+  const data = query.data;
+  if (data === undefined) return { count: null, kind: "unknown" };
+  return {
+    count: data.count,
+    kind: countKind(
+      data.count,
+      data.count_is_lower_bound,
+      data.exact_total,
+      parseDegradations(data.degraded)
+    ),
+  };
+}

package/src/headless/useScorerNames.ts

@@ -0,0 +1,36 @@
+/**
+ * Scorer SLUGS turned into the names the disclosure already gives them.
+ *
+ * `degraded[]` reports a scorer the engine could not evaluate as
+ * `"scorer:geo_decay"` — a registry identifier, because that is the only
+ * handle the query envelope has. Printed straight into a sentence it reads
+ * "The ranking parameter “geo_decay” was not applied", which is a developer's
+ * word in a shopper's banner (class C-DEVCOPY).
+ *
+ * The name is not this pair's to invent: the backend already publishes one per
+ * scorer on `GET /ranking` (`description_key`, a translation key). So the
+ * lookup goes there — through the SAME cache entry `<RankingDisclosure>`
+ * fills, with `enabled: false`, so a result page never issues a second request
+ * for a label. When the disclosure has not been read the map is empty and the
+ * banner falls back to the slug, which is what it said before and is at least
+ * traceable.
+ */
+import { useT } from "@stapel/core";
+import { useRankingDisclosure } from "../model/queries.js";
+import { useSearchState } from "./SearchStateProvider.js";
+
+/** `(slug) => name`, or `undefined` when nothing in cache names that slug. */
+export type ScorerNameLookup = (slug: string) => string | undefined;
+
+export function useScorerNames(): ScorerNameLookup {
+  const t = useT();
+  const { state } = useSearchState();
+  const query = useRankingDisclosure(state.type, { enabled: false });
+  const scorers = query.data?.scorers;
+  return (slug: string) => {
+    const scorer = scorers?.find((candidate) => candidate.slug === slug);
+    if (scorer === undefined) return undefined;
+    const named = t(scorer.description_key);
+    return named.length > 0 && named !== scorer.description_key ? named : undefined;
+  };
+}