@stapel/search-react 0.12.0 → 0.14.0

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/search-react",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "defined": [],
   "flows": []
 }

package/src/default/LocationSummaryLine.tsx

@@ -27,34 +27,139 @@
  *
  * `<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.
+ * on it, so it 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.
+ *
+ * ## The row overlapped itself on a phone, and why (defect C12)
+ *
+ * Measured on a live 390px SERP, in both themes, on every result page:
+ *
+ * ```
+ * {"kind":"clipped-left","t":"A chosen place on the map","x":-4}
+ * {"kind":"overlap","a":"· Within 25 km","b":"Filters","px":43}
+ * ```
+ *
+ * Three separate causes, and none of them was the flex row itself:
+ *
+ * 1. **An antd `<Button>` CENTRES its content.** `minWidth: 0` let the left
+ *    item shrink, and nothing clipped what was inside it, so the label
+ *    overflowed its box symmetrically — off the left edge of the screen at
+ *    `x = -4` and 43px across the word "Filters" at the other end. A shrunk
+ *    box with no `overflow` is not a truncation, it is an overlap.
+ * 2. **Nothing declared which end may shrink.** Both ends were `1 1 auto`, so
+ *    a long place name took width from a word that must never lose any.
+ * 3. **The count was an antd `<Badge count>`,** which is an absolutely
+ *    positioned `sup` hung off the top-right CORNER of what it wraps. At the
+ *    trailing edge of a full-width row that lands it outside the row entirely
+ *    — a red plaque floating in the corner of the page, attached to nothing
+ *    (measured at `y = 72` for a row whose own line is at `y = 93`).
+ *
+ * So: one compact line, `place · radius` on the left and `Filters` right; the
+ * left is the only half that shrinks and it truncates with an ellipsis; the
+ * count rides IN the flow beside the word it counts for. The first two rules
+ * are what an inline style cannot reach (they belong on the wrapper antd puts
+ * around a button's children), which is why this file hoists a stylesheet the
+ * way `<ListingCard>` and `<SkinCarousel>` do.
  */
 import { useState } from "react";
 import type { CSSProperties, ReactElement, ReactNode } from "react";
-import { Badge, Button, Flex } from "antd";
+import { Button, Flex } from "antd";
 import { useT } from "@stapel/core";
-import { spacing } from "@stapel/tokens";
+import { cssVar, fontSize, radii, 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 class the row carries, for {@link locationLineCss}. */
+export const LOCATION_LINE_CLASS = "stapel-search-location-line";
+/** The class the shrinking half carries. */
+export const LOCATION_LINE_WHERE_CLASS = "stapel-search-location-line-where";
+/** The class the truncating label carries. */
+export const LOCATION_LINE_LABEL_CLASS = "stapel-search-location-line-label";
+/** The class the fixed half carries. */
+export const LOCATION_LINE_END_CLASS = "stapel-search-location-line-end";
+
+/** The `href` the hoisted stylesheet is deduplicated by. */
+export const LOCATION_LINE_STYLE_HREF = "stapel-search-location-line";
+
+/**
+ * The rules that keep the line ONE line — and that an inline style cannot
+ * reach, because they belong on the `<span>` antd wraps a button's children
+ * in. See the file header (defect C12) for what each of them stops.
+ *
+ * Static: nothing here varies per instance, so one hoisted copy serves a page
+ * in either theme.
+ */
+export function locationLineCss(): string {
+  const row = `.${LOCATION_LINE_CLASS}`;
+  const where = `.${LOCATION_LINE_WHERE_CLASS}`;
+  const label = `.${LOCATION_LINE_LABEL_CLASS}`;
+  const end = `.${LOCATION_LINE_END_CLASS}`;
+  return [
+    // `min-width:0` on the row too: a flex item's default `min-width:auto`
+    // is what makes a nested flex row refuse to shrink at all.
+    `${row}{min-inline-size:0}`,
+    // The ONLY half that shrinks, and it CLIPS what it cannot show. An antd
+    // Button is already a flex row and it CENTRES its children, so without
+    // these two the box shrank and its content overflowed both edges at once
+    // — the whole defect: `x:-4` on the left, 43px over "Filters" on the
+    // right.
+    `${where}{flex:1 1 auto;min-inline-size:0;overflow:hidden;` +
+      `justify-content:flex-start}`,
+    // Whatever the button puts its children in has to be allowed to shrink;
+    // a flex item's `min-width:auto` refuses to go below its content.
+    `${where}>span{min-inline-size:0}`,
+    // `display:block` is load-bearing: `text-overflow` applies to a BLOCK
+    // container and does nothing on a flex one, so a label that had been
+    // turned into a flex box truncated with a hard cut mid-glyph instead of
+    // an ellipsis.
+    `${label}{display:block;min-inline-size:0;overflow:hidden;` +
+      `text-overflow:ellipsis;white-space:nowrap}`,
+    // The word a person is looking for never loses a pixel to a place name.
+    `${end}{flex:0 0 auto}`,
+  ].join("");
+}
+
 /** 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. */
+/** The shrinking half. The flex rules it needs live in the hoisted sheet
+ * (they have to reach antd's own wrapper span); this is the chrome. */
 const LOCATION: CSSProperties = {
-  minWidth: 0,
   paddingInline: 0,
   textAlign: "start",
 };
 
+/** The pin, which is not allowed to shrink either — a squashed glyph is
+ * noise, and it costs 16px. */
+const PIN: CSSProperties = { flex: "0 0 auto", display: "inline-flex" };
+
+/**
+ * The count, IN the flow.
+ *
+ * An antd `<Badge count>` is an absolutely positioned `sup` on the corner of
+ * whatever it wraps, and at the trailing edge of a full-width row that puts it
+ * outside the row: a red plaque in the corner of the page attached to nothing.
+ * A pill beside the word is the same fact, in the line it belongs to, and it
+ * takes part in the layout instead of floating over it.
+ */
+const COUNT: CSSProperties = {
+  display: "inline-block",
+  minInlineSize: `${String(spacing[4])}px`,
+  paddingInline: spacing[1],
+  borderRadius: radii.full,
+  background: cssVar("brand"),
+  color: cssVar("text-on-accent"),
+  fontSize: fontSize.xs.fontSize,
+  lineHeight: `${String(spacing[4])}px`,
+  textAlign: "center",
+};
+
 export interface LocationSummaryLineProps {
   /**
    * The location control the sheet opens onto — the same slot the panel and
@@ -123,18 +228,26 @@ export function LocationSummaryLine(
 
   return (
     <>
+      <style href={LOCATION_LINE_STYLE_HREF} precedence="default">
+        {locationLineCss()}
+      </style>
       <Flex
         align="center"
         justify="space-between"
         gap={spacing[2]}
         style={ROW}
+        className={LOCATION_LINE_CLASS}
         data-testid="search-location-summary"
         data-geo={geo === undefined ? "off" : "on"}
       >
+        {/* The glyph is rendered as a CHILD rather than through antd's `icon`
+            prop: the icon slot sits outside the wrapper span, so the label
+            beside it could not be given a min-width of its own — and a label
+            that cannot shrink is a label that overflows. */}
         <Button
           type="link"
           style={LOCATION}
-          icon={<PinGlyph />}
+          className={LOCATION_LINE_WHERE_CLASS}
           data-testid="search-location-open"
           data-analytics="none"
           data-analytics-reason="opening the location sheet is a read, not a flow step"
@@ -142,13 +255,21 @@ export function LocationSummaryLine(
             setOpen(true);
           }}
         >
-          {where}
-          {radius !== undefined && (
-            <span data-testid="search-location-radius">
-              {" · "}
-              {radius}
-            </span>
-          )}
+          <span style={PIN}>
+            <PinGlyph />
+          </span>
+          <span
+            className={LOCATION_LINE_LABEL_CLASS}
+            data-testid="search-location-label"
+          >
+            {where}
+            {radius !== undefined && (
+              <span data-testid="search-location-radius">
+                {" · "}
+                {radius}
+              </span>
+            )}
+          </span>
         </Button>
 
         {/* "Filters", not "All filters": this end of the row shares 390px
@@ -156,10 +277,12 @@ export function LocationSummaryLine(
             the person is looking for is the noun. The panel's own heading
             still says "All filters" — there it is naming a sheet, not a
             door. */}
-        {/* The count, not a dot: this row has the width to say how many. */}
-        <Badge
-          count={activeFilters}
-          size="small"
+        {/* The count, not a dot: this row has the width to say how many — and
+            it rides IN the line rather than floating off its corner. */}
+        <Flex
+          align="center"
+          gap={spacing[1]}
+          className={LOCATION_LINE_END_CLASS}
           data-testid="search-location-filters-badge"
         >
           <Button
@@ -173,7 +296,12 @@ export function LocationSummaryLine(
           >
             {t(SEARCH_I18N_KEYS.filtersShort)}
           </Button>
-        </Badge>
+          {activeFilters > 0 && (
+            <span style={COUNT} data-testid="search-location-filters-count">
+              {activeFilters}
+            </span>
+          )}
+        </Flex>
       </Flex>
 
       <GeoSheet

package/src/default/SearchResultCard.tsx

@@ -18,11 +18,14 @@
  *
  * ── 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.
+ * 1. **It read a photo shape nothing in this fleet emits.** `card.image` was
+ *    read as an object with a `url` key and `card.image_url` as the fallback;
+ *    what the fleet actually stores is a `<type>/<hash>` CDN reference, and
+ *    where it does store an object that object carries `ref` + `variants[]`
+ *    and no top-level `url`. So every consumer that did not pass its own
+ *    `renderCard` got a card with no photo at all. `cardPhotos.ts` reads the
+ *    real shapes, through the runtime's `resolveImage` seam, and the whole
+ *    `images[]` gallery rather than one photo.
  * 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
@@ -47,11 +50,14 @@ 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 { SkinCarousel } from "@stapel/tokens-antd/skin";
 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 { useSearchRuntime } from "../model/context.js";
+import { readCardPhotos } from "./cardPhotos.js";
+import type { CardPhotos } from "./cardPhotos.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
 /** What the card slot is handed. */
@@ -78,7 +84,11 @@ export const GENERIC_CARD_FIELDS: readonly string[] = [
   "price",
   "currency",
   "location",
-  "image_url",
+  // The gallery, and the singular first photo the projection keeps beside it
+  // (`images[0]`). Both hold CDN references; see `cardPhotos.ts`. The old
+  // `image_url` is gone — no backend in this fleet ever wrote it.
+  "images",
+  "image",
   "url",
 ];
 
@@ -150,41 +160,130 @@ const PROMOTED_TAG: CSSProperties = {
   whiteSpace: "nowrap",
 };
 
-/** The photo's box: a 4:3 well the image fills, drawn before it loads. */
-const PHOTO: CSSProperties = {
+/**
+ * The shape of one photo well, everywhere on this card. Declared once so the
+ * placeholder and the loaded photo cannot drift into two different crops, and
+ * so the well is on screen before the network answers.
+ */
+const CARD_PHOTO_ASPECT = "4 / 3";
+
+/** The placeholder well: the box the photo would have occupied. */
+const PHOTO_ABSENT: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: spacing[1],
   width: "100%",
-  aspectRatio: "4 / 3",
+  aspectRatio: CARD_PHOTO_ASPECT,
   overflow: "hidden",
   borderRadius: radii.md,
   background: cssVar("surface-sunken"),
+  color: cssVar("text-muted"),
 };
 
+/** The slide's own fill — the strip's well owns the shape. */
+const PHOTO_FILL: CSSProperties = { width: "100%", height: "100%" };
+
+/** A camera outline in `currentColor` — no icon dependency, and it inherits
+ * the theme rather than carrying a colour. `aria-hidden` because the sentence
+ * beside it is the label. */
+function CameraGlyph(): ReactElement {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 8.5A2.5 2.5 0 0 1 5.5 6h1.7l1.2-2h6.2l1.2 2h1.7A2.5 2.5 0 0 1 20 8.5v8A2.5 2.5 0 0 1 17.5 19h-11A2.5 2.5 0 0 1 4 16.5z" />
+      <circle cx="12" cy="12.5" r="3.2" />
+    </svg>
+  );
+}
+
 /**
- * A plain `image_url` as the descriptor `<Image>` consumes.
+ * The card's photos — the whole gallery, as a swipeable strip.
+ *
+ * ── Why the strip is OUTSIDE the card's anchor ────────────────────────────
+ *
+ * `<SkinCarousel>` is a scroll container with its own tab stop, and a
+ * horizontal swipe that ends inside an `<a>` is a swipe the browser may
+ * deliver as a click. Inside the anchor, every attempt to look at photo two
+ * would navigate to the result — the defect that makes phone galleries
+ * unusable. So it sits above the anchor as a sibling, exactly as
+ * `<ListingSerpCard>` does it, and the anchor still covers everything a
+ * person reads.
  *
- * 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.
+ * Three states, and they are three different facts. No photo FIELD at all —
+ * a doc type that indexes text — draws nothing, because reserving a 4:3 well
+ * for a corpus that has no photos is a hole in every row. A field with
+ * nothing behind it draws the well and says the photo is unavailable: that is
+ * usually an unwired `resolveImage`, and a sentence gets it fixed where an
+ * empty grey box does not. Anything else is the strip.
  */
-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;
+function CardPhotoStrip(props: {
+  photos: CardPhotos;
+  title: string;
+}): ReactElement | null {
+  const t = useT();
+  const { photos, title } = props;
+  if (photos.stored === 0) return null;
+
+  if (photos.images.length === 0) {
+    const caption = t(SEARCH_I18N_KEYS.resultsPhotoUnavailable);
+    return (
+      <div
+        role="img"
+        aria-label={caption}
+        data-testid="search-result-photo-absent"
+        style={PHOTO_ABSENT}
+      >
+        <CameraGlyph />
+        <Typography.Text type="secondary" style={{ fontSize: fontSize.xs.fontSize }}>
+          {caption}
+        </Typography.Text>
+      </div>
+    );
   }
-  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: [],
-  };
+
+  const total = photos.images.length;
+  // A one-photo strip gets neither a peek nor dots: the sliver of a next
+  // slide is an affordance for something that is there.
+  const many = total > 1;
+  return (
+    <SkinCarousel
+      label={t(SEARCH_I18N_KEYS.resultsPhotos)}
+      aspectRatio={CARD_PHOTO_ASPECT}
+      peek={many}
+      dots={many}
+      data-testid="search-result-photos"
+    >
+      {photos.images.map((image, index) => (
+        <Image
+          key={`${String(index)}:${image.url}`}
+          meta={image}
+          alt={
+            many
+              ? t(SEARCH_I18N_KEYS.resultsPhotoAlt, {
+                  index: index + 1,
+                  total,
+                  title,
+                })
+              : t(SEARCH_I18N_KEYS.resultsImageAlt, { title })
+          }
+          fit="cover"
+          data-testid="search-result-photo"
+          style={PHOTO_FILL}
+        />
+      ))}
+    </SkinCarousel>
+  );
 }
 
 /**
@@ -208,6 +307,7 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
   const t = useT();
   const format = useFormat();
   const card = props.item.card;
+  const resolve = useSearchRuntime().resolveImage;
   const title = text(card["title"]) ?? t(SEARCH_I18N_KEYS.resultsUntitled);
   const price = formatCardPrice(format, text(card["price"]), text(card["currency"]));
   const href = text(card["url"]);
@@ -218,48 +318,32 @@ 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]);
+  // Memoised on the card and the resolver: a host resolver is a plain
+  // function returning a fresh object, so resolving inline hands `<Image>` a
+  // new `meta` identity on every render — a load it then has to decide is or
+  // is not the same one.
+  const photos = useMemo(() => readCardPhotos(card, resolve), [card, resolve]);
 
   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
+          strong
+          style={{ fontSize: fontSize.lg.fontSize }}
+          data-testid="search-result-price"
+        >
+          {price}
+        </Typography.Text>
+      )}
+      {(location !== undefined || distance !== undefined) && (
+        <Typography.Text type="secondary">
+          {[location, distance].filter((v) => v !== undefined).join(" · ")}
+        </Typography.Text>
       )}
-      <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
-            strong
-            style={{ fontSize: fontSize.lg.fontSize }}
-            data-testid="search-result-price"
-          >
-            {price}
-          </Typography.Text>
-        )}
-        {(location !== undefined || distance !== undefined) && (
-          <Typography.Text type="secondary">
-            {[location, distance].filter((v) => v !== undefined).join(" · ")}
-          </Typography.Text>
-        )}
-      </Flex>
     </Flex>
   );
 
@@ -272,6 +356,8 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
       styles={{ body: { padding: spacing[3] } }}
     >
       <Flex vertical gap={spacing[2]}>
+        {/* A SIBLING of the anchor, never a child — see `CardPhotoStrip`. */}
+        <CardPhotoStrip photos={photos} title={title} />
         {href === undefined ? (
           body
         ) : (