@stapel/search-react 0.4.0 → 0.7.0

package/src/default/SearchResultCard.tsx

@@ -15,10 +15,42 @@
  * every sort, and a storefront where some lists show it and some do not is
  * legally worse than one that never showed it. `renderCard` receives the whole
  * item so the marking is always reachable, and this default renders it.
+ *
+ * ── Two things this card used to get wrong ────────────────────────────────
+ *
+ * 1. **It declared `image_url` and drew nothing.** A text-only card in a
+ *    classifieds search is not a card; the field was in `GENERIC_CARD_FIELDS`
+ *    and in no render path. It is drawn now, through `@stapel/image`, so the
+ *    aspect box lands before the network does and a dead URL renders a named
+ *    placeholder instead of the browser's torn-page icon.
+ * 2. **The marking's EXPLANATION was in a `Tooltip`.** Touch has no hover, so
+ *    on the device most of this traffic arrives from, the sentence the law is
+ *    actually about was unreachable — the tag said "Promoted" and nothing on
+ *    screen said what that meant. It is ordinary text under the tag now
+ *    (`stapel/no-tooltip-in-skin`), and the tag itself is a `--stapel-*` role
+ *    rather than an antd preset, because the one legally-mandated marking in
+ *    the pair has to look the same in every skin a deployment builds.
+ * 3. **The tag was white on cream.** `warning-on` is the text colour for the
+ *    SOLID warning fill; over `warning-bg` the readable role is `warning`
+ *    itself. The visual pass measured the one legally-mandated string in the
+ *    package at roughly 1.2:1 — a disclosure nobody can read is the same as
+ *    no disclosure, in both themes.
+ * 4. **The price was a raw amount and an ISO code.** "3200 RUB" is a wire
+ *    value printed as prose: no grouping, no symbol, and the code in the
+ *    reader's face. It goes through core's `useFormat().number` with
+ *    `style: "currency"`, which is the same `Intl` path `@stapel/currencies-
+ *    react`'s `formatMoney` takes — this pair does not depend on that package
+ *    (a search index is not a price book) but it must not invent a second
+ *    way to write money either.
  */
-import type { ReactElement, ReactNode } from "react";
-import { Card, Flex, Tag, Tooltip, Typography } from "antd";
-import { useT } from "@stapel/core";
+import { useMemo } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Card, Flex, Typography } from "antd";
+import { Image } from "@stapel/image";
+import type { StapelImage } from "@stapel/image";
+import { useFormat, useT } from "@stapel/core";
+import type { Format } from "@stapel/core";
+import { cssVar, fontSize, fontWeight, radii, spacing } from "@stapel/tokens";
 import type { SearchItem } from "../api/types.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
@@ -47,14 +79,138 @@ export const GENERIC_CARD_FIELDS: readonly string[] = [
   "currency",
   "location",
   "image_url",
+  "url",
 ];
 
+/**
+ * The card's price, written the way money is written.
+ *
+ * `card.price` arrives as a string because the index stores it as one, and
+ * `card.currency` as an ISO 4217 code because that is what a document carries.
+ * Rendered verbatim they read "3200 RUB": no grouping, the code where the
+ * symbol belongs, and the reader doing the arithmetic of where the thousands
+ * are. `Intl` knows all of that per locale, so the code goes in and the
+ * locale's own rendering comes out.
+ *
+ * Two ways this refuses to guess. A `price` that is not a finite number is
+ * passed through UNCHANGED — a doc type may store "on request", and turning
+ * that into `NaN` or into nothing loses what the seller wrote. A `currency`
+ * that is not a three-letter code (or one this runtime rejects) falls back to
+ * the plain grouped number plus the code, which is still better than the raw
+ * pair and never throws inside a render.
+ */
+export function formatCardPrice(
+  format: Format,
+  price: string | undefined,
+  currency: string | undefined
+): string | undefined {
+  if (price === undefined) return undefined;
+  const amount = Number(price);
+  if (!Number.isFinite(amount)) return price;
+  if (currency !== undefined && /^[A-Za-z]{3}$/.test(currency)) {
+    try {
+      const money = format.number(amount, {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        currencyDisplay: "narrowSymbol",
+        maximumFractionDigits: Number.isInteger(amount) ? 0 : 2,
+      });
+      if (money !== null) return money;
+    } catch {
+      // An unsupported currency code: fall through to the grouped number.
+    }
+  }
+  const grouped = format.number(amount);
+  if (grouped === null) return price;
+  return currency === undefined ? grouped : `${grouped} ${currency}`;
+}
+
+/**
+ * The DSA Art. 26 marking, as a token role.
+ *
+ * `warning` is the §68 dictionary's "look at this, it is not an error" role —
+ * the same one every skin in the fleet resolves from its own theme JSON. The
+ * previous `<Tag color="gold">` was an antd PRESET: it survived a retheme
+ * unchanged, so a deployment with its own palette had one component still
+ * painted in Ant Design's gold, and the one marking that must be recognisable
+ * everywhere was the one thing the design system did not own.
+ */
+const PROMOTED_TAG: CSSProperties = {
+  alignSelf: "flex-start",
+  background: cssVar("warning-bg"),
+  // `warning`, not `warning-on`: the latter is the text colour for the SOLID
+  // warning fill (white on light), and over `warning-bg` it is cream on cream.
+  color: cssVar("warning"),
+  fontWeight: fontWeight.medium,
+  border: `1px solid ${cssVar("warning-border")}`,
+  borderRadius: radii.sm,
+  padding: `0 ${String(spacing[2])}px`,
+  fontSize: fontSize.xs.fontSize,
+  lineHeight: `${String(fontSize.md.lineHeight)}px`,
+  whiteSpace: "nowrap",
+};
+
+/** The photo's box: a 4:3 well the image fills, drawn before it loads. */
+const PHOTO: CSSProperties = {
+  width: "100%",
+  aspectRatio: "4 / 3",
+  overflow: "hidden",
+  borderRadius: radii.md,
+  background: cssVar("surface-sunken"),
+};
+
+/**
+ * A plain `image_url` as the descriptor `<Image>` consumes.
+ *
+ * A doc type that stores a bare URL has no variant ladder and no dimensions —
+ * `source: "link"` is exactly that case, and `<Image>` degrades to the single
+ * URL rather than pretending to shop a tier. A doc type that stores the whole
+ * `StapelImage` snapshot (`card.image`) gets the ladder, blur-up and all.
+ */
+function cardImage(card: Readonly<Record<string, unknown>>): StapelImage | undefined {
+  const rich = card["image"];
+  if (rich !== null && typeof rich === "object" && "url" in rich) {
+    return rich as StapelImage;
+  }
+  const url = text(card["image_url"]);
+  if (url === undefined) return undefined;
+  return {
+    source: "link",
+    url,
+    mime: null,
+    width: null,
+    height: null,
+    aspect: null,
+    square: false,
+    preview_b64: null,
+    variants: [],
+  };
+}
+
+/**
+ * The whole card as ONE tap target.
+ *
+ * A catalogue row is a link — the person taps the picture, the title or the
+ * price and expects the same thing to happen. The card used to have no
+ * clickable anything at all: the entire result page of a storefront that had
+ * not passed `renderCard` was a wall of text with the tap target missing
+ * (class C-NOPRIMARY). `card.url` is the conventional field a doc type stores
+ * it in; without one the card stays exactly what it was, because inventing a
+ * destination is worse than not having one.
+ */
+const CARD_LINK: CSSProperties = {
+  color: "inherit",
+  display: "block",
+  textDecoration: "none",
+};
+
 export function SearchResultCard(props: SearchCardProps): ReactElement {
   const t = useT();
+  const format = useFormat();
   const card = props.item.card;
   const title = text(card["title"]) ?? t(SEARCH_I18N_KEYS.resultsUntitled);
-  const price = text(card["price"]);
-  const currency = text(card["currency"]);
+  const price = formatCardPrice(format, text(card["price"]), text(card["currency"]));
+  const href = text(card["url"]);
   const location = text(card["location"]);
   const distance =
     props.item.distance_km !== null
@@ -62,27 +218,40 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
           km: props.item.distance_km.toFixed(1),
         })
       : undefined;
+  // Memoised on the two fields it reads: a fresh `meta` identity every render
+  // is a load `<Image>` has to decide is or is not the same one.
+  const image = useMemo(() => cardImage(card), [card]);
 
-  return (
-    <Card
-      size="small"
-      data-testid="search-result-card"
-      data-promoted={props.item.promoted ? "true" : "false"}
-    >
-      <Flex vertical gap={4}>
-        <Flex justify="space-between" align="start" gap={8}>
-          <Typography.Text strong>{title}</Typography.Text>
-          {props.item.promoted && (
-            <Tooltip title={t(SEARCH_I18N_KEYS.resultsPromotedHint)}>
-              <Tag color="gold" data-testid="search-result-promoted">
-                {t(SEARCH_I18N_KEYS.resultsPromoted)}
-              </Tag>
-            </Tooltip>
-          )}
-        </Flex>
+  const body = (
+    <Flex vertical gap={spacing[2]}>
+      {image !== undefined && (
+        <div style={PHOTO} data-testid="search-result-photo">
+          {/* The WELL owns the shape (4:3, drawn before the network answers),
+              so the image is told to fill it. Without an explicit box the
+              image's own container reserves height only from the snapshot's
+              `aspect` — which a doc type storing a bare `image_url` does not
+              have — and a `cover` image inside a zero-height parent is a
+              photo that loaded and was never seen. */}
+          <Image
+            meta={image}
+            alt={t(SEARCH_I18N_KEYS.resultsImageAlt, { title })}
+            fit="cover"
+            style={{ width: "100%", height: "100%" }}
+          />
+        </div>
+      )}
+      <Flex vertical gap={spacing[1]}>
+        <Typography.Text strong>{title}</Typography.Text>
+        {/* The price is the strongest line on a catalogue card: it is what
+            the eye scans a grid for. It used to share a type step with the
+            location and sit under a disclosure three times its size. */}
         {price !== undefined && (
-          <Typography.Text>
-            {currency !== undefined ? `${price} ${currency}` : price}
+          <Typography.Text
+            strong
+            style={{ fontSize: fontSize.lg.fontSize }}
+            data-testid="search-result-price"
+          >
+            {price}
           </Typography.Text>
         )}
         {(location !== undefined || distance !== undefined) && (
@@ -91,6 +260,44 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
           </Typography.Text>
         )}
       </Flex>
+    </Flex>
+  );
+
+  return (
+    <Card
+      size="small"
+      data-testid="search-result-card"
+      data-promoted={props.item.promoted ? "true" : "false"}
+      {...(href !== undefined ? { hoverable: true } : {})}
+      styles={{ body: { padding: spacing[3] } }}
+    >
+      <Flex vertical gap={spacing[2]}>
+        {href === undefined ? (
+          body
+        ) : (
+          <a href={href} style={CARD_LINK} data-testid="search-result-link">
+            {body}
+          </a>
+        )}
+        {props.item.promoted && (
+          <Flex vertical gap={spacing[1]} data-testid="search-result-promotion">
+            <span style={PROMOTED_TAG} data-testid="search-result-promoted">
+              {t(SEARCH_I18N_KEYS.resultsPromoted)}
+            </span>
+            {/* The explanation the marking exists FOR. Visible, on every
+                device, because a legal disclosure that needs a mouse is a
+                disclosure a phone never receives — as a caption, so it marks
+                the card rather than outweighing what is for sale on it. */}
+            <Typography.Text
+              type="secondary"
+              style={{ fontSize: fontSize.xs.fontSize }}
+              data-testid="search-result-promoted-hint"
+            >
+              {t(SEARCH_I18N_KEYS.resultsPromotedHint)}
+            </Typography.Text>
+          </Flex>
+        )}
+      </Flex>
     </Card>
   );
 }

package/src/default/SearchResultsPane.tsx

@@ -2,9 +2,9 @@
  * `<SearchResultsPane>` — the antd result page: the count, the degradation
  * banner, the cards, and the keyset controls.
  *
- * Rendered through core's `matchList`, whose FOUR required arms are the point.
- * "Nothing matches this search" is reachable only from a search that actually
- * ran; a 5xx renders "we could not run this search" plus a retry. The
+ * Rendered through the shared substrate's `LoadList`, whose FOUR arms are the
+ * point. "Nothing matches this search" is reachable only from a search that
+ * actually ran; a 5xx renders "we could not run this search" plus a retry. The
  * substitution of one for the other is what cost the 2026-08-09 incident, and
  * the spec's §7.4 negative leg exercises this exact pane against a forced 5xx.
  *
@@ -12,28 +12,39 @@
  * is "narrow the search", not "there is nothing here" — it arrives as a 400
  * with an empty body, which is precisely how it would otherwise render as an
  * empty page.
+ *
+ * ── Two things the pager used to get wrong ────────────────────────────────
+ *
+ * 1. **Its reasons were in `title=`.** A disabled antd Button receives no
+ *    pointer events, so the browser tooltip never fires — on any device — and
+ *    a phone has no hover to begin with. Both buttons are `GatedButton` now:
+ *    the block's reason is ordinary text beside the control and the button's
+ *    `aria-describedby` points at it.
+ * 2. **It rendered when there was nothing to page.** Two dead buttons under an
+ *    empty state is the fleet's C-DEADPAGER defect; the pager now appears only
+ *    when the answer actually has another page in some direction.
  */
 import type { CSSProperties, ReactElement, ReactNode } from "react";
-import { Button, Empty, Flex, Spin, Typography } from "antd";
+import { Flex, Typography } from "antd";
+import { errorCode, useT, useTPlural } from "@stapel/core";
 import {
-  errorCode,
-  matchList,
-  toFlowError,
-  useDescribeFlowError,
-  useT,
-  useTPlural,
-} from "@stapel/core";
+  EmptyState,
+  ErrorAlert,
+  GatedButton,
+  LoadList,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
+import { spacing } from "@stapel/tokens";
 import type { SearchItem } from "../api/types.js";
 import { SearchResults } from "../headless/SearchResults.js";
 import type { SearchResultsBag } from "../headless/SearchResults.js";
+import { useScorerNames } from "../headless/useScorerNames.js";
 import { SEARCH_WINDOW_EXCEEDED } from "../i18n/errorsMap.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import { DegradationNotice } from "./DegradationNotice.js";
 import type { DegradationNoticeVariant } from "./DegradationNotice.js";
-import { ErrorAlert } from "./ErrorAlert.js";
 import { SearchResultCard } from "./SearchResultCard.js";
 import type { SearchCardRenderer } from "./SearchResultCard.js";
-import { SearchSkinTheme } from "./theme.js";
 import type { ThemeModeProp } from "./types.js";
 
 /**
@@ -47,6 +58,17 @@ export type SearchResultsRenderer = (
   items: readonly SearchItem[]
 ) => ReactNode;
 
+/**
+ * The widest a column of results is allowed to get.
+ *
+ * Off the spacing scale and named for it: it is a MEASURE, the reading-width
+ * decision every long page has to take. Without it the pane spread the full
+ * width of whatever it was dropped into — the visual pass measured a 2560px
+ * pane with four cards floating at the top of it and a status row 1350px from
+ * the buttons that act on it (class C-NOMAXW).
+ */
+export const RESULTS_MAX_WIDTH = 1120;
+
 /**
  * The results grid. `auto-fill` + `minmax(280px, 1fr)`: as many columns as fit,
  * each at least a readable card and never wider than its share — a catalogue
@@ -58,7 +80,7 @@ export type SearchResultsRenderer = (
 const RESULTS_GRID: CSSProperties = {
   display: "grid",
   gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))",
-  gap: 12,
+  gap: spacing[3],
   alignItems: "stretch",
 };
 
@@ -81,6 +103,21 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    * toolbar in here instead of printing a second caption above the pane.
    */
   readonly toolbar?: ReactNode;
+  /**
+   * What this list is CALLED on this surface. Default: "Results".
+   *
+   * The pane owning the heading row is what stops a screen printing two
+   * captions — but "Results" is only the right word when the person performed
+   * a search. A landing's newest-first strip is "Fresh listings"; a seller's
+   * page is "This seller's listings"; a category page's is the category. Every
+   * one of those surfaces had written its own `<Title>` above the pane and got
+   * the pane's "Results" underneath it a moment later — two headings, one
+   * list, on the three busiest screens of the storefront.
+   *
+   * So the name comes IN, to the row that already exists, instead of being
+   * printed a second time above it. Still exactly one heading either way.
+   */
+  readonly heading?: ReactNode;
   /** Rendered under the pager — where the container puts the ranking link. */
   readonly footer?: ReactNode;
   /**
@@ -95,6 +132,9 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
    */
   readonly degradationNotice?: DegradationNoticeVariant;
   readonly enabled?: boolean;
+  /** Widest the column of results may grow (default {@link RESULTS_MAX_WIDTH});
+   * `null` lets the container decide. */
+  readonly maxWidth?: number | null;
 }
 
 function Count(props: { bag: SearchResultsBag }): ReactElement | null {
@@ -121,50 +161,69 @@ function Count(props: { bag: SearchResultsBag }): ReactElement | null {
   );
 }
 
-function Pager(props: { bag: SearchResultsBag }): ReactElement {
+/**
+ * The keyset controls — rendered only when there IS another page.
+ *
+ * Keyset paging has no page numbers to jump to: there is a next, a previous,
+ * and a server-side depth cap. When neither direction exists the pager is not
+ * "disabled", it is absent — a control that can never do anything is not a
+ * control that needs explaining.
+ */
+function Pager(props: { bag: SearchResultsBag }): ReactElement | null {
   const t = useT();
-  const { prev, next, goPrev, goNext } = props.bag;
+  const { page, prev, next, goPrev, goNext } = props.bag;
+  if (page === null || (!page.hasNext && !page.hasPrev)) return null;
   return (
-    <Flex gap={8} justify="center" data-testid="search-pager">
-      <Button
-        disabled={!prev.available}
-        title={prev.available ? undefined : t(prev.block.code, prev.block.params)}
+    <Flex gap={spacing[2]} justify="center" wrap data-testid="search-pager">
+      <GatedButton
+        gate={prev}
         onClick={goPrev}
+        testId="search-prev"
         data-analytics="none"
         data-analytics-reason="keyset paging is a read, not a flow step"
-        data-testid="search-prev"
       >
         {t(SEARCH_I18N_KEYS.resultsPrev)}
-      </Button>
-      <Button
-        disabled={!next.available}
-        title={next.available ? undefined : t(next.block.code, next.block.params)}
+      </GatedButton>
+      <GatedButton
+        gate={next}
         onClick={goNext}
+        testId="search-next"
         data-analytics="none"
         data-analytics-reason="keyset paging is a read, not a flow step"
-        data-testid="search-next"
       >
         {t(SEARCH_I18N_KEYS.resultsNext)}
-      </Button>
+      </GatedButton>
     </Flex>
   );
 }
 
 export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
   const t = useT();
-  const describe = useDescribeFlowError();
   const { renderCard, renderResults } = props;
+  const scorerName = useScorerNames();
+  const maxWidth = props.maxWidth === undefined ? RESULTS_MAX_WIDTH : props.maxWidth;
 
   return (
-    <SearchSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+    <SkinTheme
+      surface="base"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+      style={{
+        width: "100%",
+        ...(maxWidth !== null ? { maxWidth } : {}),
+      }}
+    >
       <SearchResults {...(props.enabled !== undefined ? { enabled: props.enabled } : {})}>
         {(bag) => (
-          <Flex vertical gap={16}>
-            <Flex justify="space-between" align="center" wrap gap={8}>
-              <Typography.Title level={4} style={{ margin: 0 }}>
-                {t(SEARCH_I18N_KEYS.resultsTitle)}
+          <Flex vertical gap={spacing[4]}>
+            <Flex justify="space-between" align="center" wrap gap={spacing[2]}>
+              <Typography.Title
+                level={4}
+                style={{ margin: 0 }}
+                data-testid="search-results-heading"
+              >
+                {props.heading ?? t(SEARCH_I18N_KEYS.resultsTitle)}
               </Typography.Title>
-              <Flex align="center" wrap gap={12}>
+              <Flex align="center" wrap gap={spacing[3]}>
                 <Count bag={bag} />
                 {props.toolbar}
               </Flex>
@@ -173,49 +232,40 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
             <DegradationNotice
               degradations={bag.degradations}
               variant={props.degradationNotice ?? "banner"}
+              scorerName={scorerName}
             />
 
-            {matchList(bag.state, {
-              loading: () => (
-                <Flex justify="center" style={{ padding: 24 }}>
-                  <Spin data-testid="search-loading" />
-                </Flex>
-              ),
-              failed: (error) => {
+            <LoadList
+              state={bag.state}
+              testId="search"
+              skeletonRows={6}
+              onRetry={bag.refetch}
+              empty={
+                <EmptyState
+                  title={t(SEARCH_I18N_KEYS.resultsEmpty)}
+                  testId="search-empty"
+                />
+              }
+              failed={(error) => {
                 // The window refusal is a DIFFERENT sentence from a failed
                 // search, and both are different from "nothing found".
                 const isWindow = errorCode(error) === SEARCH_WINDOW_EXCEEDED;
                 return (
                   <ErrorAlert
                     testId={isWindow ? "search-window-exceeded" : "search-failed"}
-                    error={{
-                      ...describe(toFlowError(error)),
-                      message: t(
-                        isWindow
-                          ? SEARCH_I18N_KEYS.resultsWindowExceeded
-                          : SEARCH_I18N_KEYS.resultsLoadFailed
-                      ),
-                    }}
-                    action={
-                      <Button
-                        size="small"
-                        onClick={bag.refetch}
-                        data-analytics="none"
-                        data-analytics-reason="retry of a failed read; no flow to step"
-                      >
-                        {t(SEARCH_I18N_KEYS.resultsRetry)}
-                      </Button>
-                    }
+                    thrown={error}
+                    message={t(
+                      isWindow
+                        ? SEARCH_I18N_KEYS.resultsWindowExceeded
+                        : SEARCH_I18N_KEYS.resultsLoadFailed
+                    )}
+                    retryLabel={t(SEARCH_I18N_KEYS.resultsRetry)}
+                    onRetry={bag.refetch}
                   />
                 );
-              },
-              empty: () => (
-                <Empty
-                  data-testid="search-empty"
-                  description={t(SEARCH_I18N_KEYS.resultsEmpty)}
-                />
-              ),
-              ready: (items) => (
+              }}
+            >
+              {(items) => (
                 <div data-testid="search-results">
                   {renderResults !== undefined ? (
                     renderResults(items)
@@ -233,14 +283,14 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                     </div>
                   )}
                 </div>
-              ),
-            })}
+              )}
+            </LoadList>
 
             <Pager bag={bag} />
             {props.footer}
           </Flex>
         )}
       </SearchResults>
-    </SearchSkinTheme>
+    </SkinTheme>
   );
 }