@stapel/listings-react 0.20.0 → 0.22.0

package/src/default/ListingCard.tsx

@@ -107,7 +107,12 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Card, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
-import { ErrorAlert, GatedControl, SkinTheme } from "@stapel/tokens-antd/skin";
+import {
+  ErrorAlert,
+  GatedControl,
+  SKIN_CAROUSEL_SLIDE_CLASS,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
 import { useActionGate, useT } from "@stapel/core";
 import type { LinkComponent, SignInCtaProp } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
@@ -123,7 +128,7 @@ import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
 import { HeartIcon } from "./icons.js";
 import { SignInLink } from "./SignInLink.js";
-import { ListingPhotoStrip } from "./ListingPhoto.js";
+import { PHOTO_LINK_CLASS, ListingPhotoStrip } from "./ListingPhoto.js";
 import { ListingPrice } from "./ListingPrice.js";
 import type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";
 
@@ -230,6 +235,18 @@ export const CARD_BLEED_CLASS = "stapel-listing-card-bleed";
  */
 export const CARD_VIEWED_CLASS = "stapel-listing-card-seen";
 
+/**
+ * The class that makes a card LOOK like a target.
+ *
+ * Measured on a live 1440px grid before this pack: `box-shadow: none`,
+ * `transform: none`, the border unchanged and `cursor: auto` — a card that
+ * opens a listing and gives a person no reason to believe it does. antd's own
+ * `hoverable` was not used: it hard-codes `boxShadowCard` and nothing else, so
+ * it cannot state a border and cannot be told to stand still for somebody who
+ * asked their system for less motion.
+ */
+export const CARD_HOVER_CLASS = "stapel-listing-card-hoverable";
+
 /**
  * How far a seen card is dimmed.
  *
@@ -289,14 +306,41 @@ export function cardTargetCss(): string {
   const media = `.${CARD_MEDIA_CLASS}`;
   const main = `.${CARD_MAIN_CLASS}`;
   const bleed = `.${CARD_BLEED_CLASS}`;
+  const hover = CARD_HOVER_CLASS;
   return [
     `.${CARD_TARGET_CLASS}{display:block;color:inherit;text-decoration:none}`,
     `.${CARD_TARGET_CLASS}:focus-visible{outline:2px solid var(--listing-card-focus);outline-offset:2px}`,
+    // A PRESS, answered where the press lands (D176). The rule is on the
+    // TARGET rather than on the card's frame because that is the one element
+    // all three surfaces share: the feed tile is a bare div with this anchor
+    // over it and no card chrome at all, so a rule written for the frame
+    // reached the two surfaces that have one and missed the phone's home
+    // screen entirely. `matchMedia("(hover: hover)")` is false on that
+    // device, which makes this the ONLY feedback a finger ever gets between
+    // touching a tile and the next screen arriving.
+    `.${CARD_TARGET_CLASS}{transition:transform 90ms ease}`,
+    `.${CARD_TARGET_CLASS}:active{transform:scale(0.985)}`,
+    `@media (prefers-reduced-motion:reduce){.${CARD_TARGET_CLASS}{transition:none}` +
+      `.${CARD_TARGET_CLASS}:active{transform:none;opacity:0.9}}`,
     // The card asks about its OWN width, not the window's — see
     // `LISTING_CARD_ROW_MIN`.
     `${q}{container-type:inline-size}`,
     `${frame}{display:flex;flex-direction:column;min-inline-size:0}`,
-    `${media}{min-inline-size:0}`,
+    // THE MEDIA WELL IS CLIPPED TO THE CARD'S OWN CORNER (D180).
+    //
+    // The photo strip runs edge to edge at the top of a stacked card, so the
+    // card's rounded corner is the corner of the PICTURE. It was not being
+    // cut to it: the well was a square box inside a rounded card, and each
+    // carousel slide carried a radius of its own — so a multi-photo tile drew
+    // a rounded sliver of the next photograph in the corner where the card's
+    // curve should be, and every row of tiles on the live feed read as a set
+    // of pictures with a torn right edge. One radius, stated by the card,
+    // applied to the box that holds the pictures; the slides inside it are
+    // square because the well is what has the shape.
+    `${media}{min-inline-size:0;overflow:hidden;` +
+      `border-start-start-radius:var(--listing-card-radius);` +
+      `border-start-end-radius:var(--listing-card-radius)}`,
+    `${media} .${SKIN_CAROUSEL_SLIDE_CLASS}{border-radius:0}`,
     `${main}{display:flex;flex-direction:column;flex:1 1 auto;min-inline-size:0}`,
     // The row arm. `align-items:flex-start` so a short text column does not
     // stretch the photo, and a fixed media basis so the picture cannot grow
@@ -304,6 +348,9 @@ export function cardTargetCss(): string {
     `@container (min-width:${String(LISTING_CARD_ROW_MIN)}px){` +
       `${frame}{flex-direction:row;align-items:flex-start}` +
       `${media}{flex:0 0 ${String(LISTING_CARD_ROW_MEDIA)}px;` +
+      // Inset on every side in the row arm, so the photo is a rounded block
+      // beside the text rather than two rounded corners and two square ones.
+      `border-radius:var(--listing-card-radius);` +
       `max-inline-size:${String(LISTING_CARD_ROW_MEDIA)}px}` +
       // A full-bleed stacked card has no padding of its own to give the row
       // arm, so the row arm states its own; the reading column's padding is
@@ -311,6 +358,34 @@ export function cardTargetCss(): string {
       `${bleed}{padding-block:var(--listing-card-inset);` +
       `padding-inline-start:var(--listing-card-inset)}` +
       `}`,
+    // A linked slide. `display:block` kills the inline baseline gap under the
+    // picture, which on a grid of tiles reads as cards of unequal height; the
+    // ring is for a browser that focuses an `aria-hidden` anchor anyway.
+    `.${PHOTO_LINK_CLASS}{display:block}`,
+    `.${PHOTO_LINK_CLASS}:focus-visible{outline:2px solid var(--listing-card-focus);outline-offset:2px}`,
+    // The card says it is a target. Two properties, both from the theme's own
+    // tokens, and a transition that a person who asked for less motion does
+    // not get.
+    `.${hover}{transition:box-shadow 160ms ease,border-color 160ms ease}`,
+    // HOVER IS FOR A POINTER THAT HAS ONE. Measured on the phone this loop
+    // walks: `matchMedia("(hover: hover)")` is false, and an unguarded
+    // `:hover` on a touch device is worse than absent — it latches after a
+    // tap and leaves one tile lit until something else is touched.
+    `@media (hover:hover){.${hover}:hover{` +
+      `box-shadow:var(--listing-card-hover-shadow);` +
+      `border-color:var(--listing-card-focus)}}`,
+    // PRESSED, and not the same thing as hovered. The card had a hover state
+    // and nothing at all on the way down, so a tap on a phone — where there
+    // is no hover to begin with — gave no feedback between the finger landing
+    // and the next screen arriving. The lift is TAKEN AWAY rather than
+    // increased: a pressed card is a card pushed into the page, which is the
+    // one direction a shadow can say without a second token.
+    `.${hover}:active{box-shadow:none;border-color:var(--listing-card-focus)}`,
+    // The photo is the largest target on the tile and is its own link, so it
+    // answers a press on its own — the card behind it may not be under the
+    // finger at all.
+    `.${PHOTO_LINK_CLASS}:active{opacity:0.88}`,
+    `@media (prefers-reduced-motion:reduce){.${hover}{transition:none}}`,
     // Already seen. The photo and everything inside the card's anchor dim
     // together; the heart is outside the anchor and stays as it was — see
     // CARD_VIEWED_CLASS.
@@ -553,9 +628,23 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         />
       ) : null}
 
+      {/* ONE line, and it truncates (D185). Measured on a live 1440px feed:
+          a two-part city-and-district name wrapped, the text block grew
+          104 -> 128px, and the two cards on either side of it stood 24px
+          shorter — a row of tiles with a ragged bottom edge and a heart
+          hanging below the line it belongs to. The place is a subtitle, not
+          prose: which city it is reads from the first words, and the tile's
+          height must be a property of the GRID rather than of how long this
+          particular neighbourhood is called. The full string stays in the
+          title attribute the way `ellipsis` puts it there, so nothing is
+          lost — it is one hover, or the listing's own page. */}
       {listing.location_label !== undefined &&
       listing.location_label.length > 0 ? (
-        <Typography.Text type="secondary" data-testid="listings-card-location">
+        <Typography.Text
+          type="secondary"
+          ellipsis={{ tooltip: listing.location_label }}
+          data-testid="listings-card-location"
+        >
           {listing.location_label}
         </Typography.Text>
       ) : null}
@@ -577,11 +666,12 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
-        // Both only when the server actually said so: absent and `null` leave
-        // the card byte-identical to what it renders today.
-        {...(viewed
-          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
-          : {})}
+        // `viewed` only when the server actually said so: absent and `null`
+        // leave the card's dimming exactly as it renders today.
+        className={
+          viewed ? `${CARD_HOVER_CLASS} ${CARD_VIEWED_CLASS}` : CARD_HOVER_CLASS
+        }
+        {...(viewed ? { "data-listing-viewed": "true" } : {})}
         // The body's own padding is zero because the frame fills the card and
         // the photo runs edge to edge when it is stacked: padding here would
         // be a strip of card around a picture. The text block inside the
@@ -591,18 +681,31 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         style={{
           ["--listing-card-focus" as string]: token.colorPrimary,
           ["--listing-card-inset" as string]: `${String(token.paddingSM)}px`,
+          // The card's OWN corner, handed to the media well so the picture is
+          // cut to the same curve the card is drawn with — in whatever theme,
+          // at whatever radius a deployment retuned it to.
+          ["--listing-card-radius" as string]: `${String(token.borderRadiusLG)}px`,
+          // The theme's own elevation, so the lift is the same one every
+          // raised surface in the skin uses and it is right in both modes.
+          ["--listing-card-hover-shadow" as string]: token.boxShadowSecondary,
         }}
       >
         <div className={CARD_QUERY_CLASS}>
           <div className={`${CARD_FRAME_CLASS} ${CARD_BLEED_CLASS}`}>
-            {/* The photos, OUTSIDE the anchor — see `<ListingPhotoStrip>`.
-                A swipeable strip is a control, and a link may not contain
-                one; the anchor still covers everything a person reads. */}
+            {/* The STRIP is outside the anchor — a swipeable scroller is a
+                control and a link may not contain one — but each SLIDE is
+                linked, so the 267x200 photograph is part of the card's target
+                instead of the one place on it where a click does nothing.
+                See `<ListingPhotoStrip>` for where that line is drawn. */}
             <div className={CARD_MEDIA_CLASS}>
               <ListingPhotoStrip
                 images={listing.images ?? []}
                 title={title.length > 0 ? title : String(listing.id)}
                 testId="listings-card-photos"
+                {...(props.href !== undefined ? { href: props.href } : {})}
+                {...(props.href !== undefined && props.linkComponent !== undefined
+                  ? { linkComponent: props.linkComponent }
+                  : {})}
               />
             </div>
 

package/src/default/ListingPhoto.tsx

@@ -27,10 +27,22 @@ import { Typography, theme as antdTheme } from "antd";
 import { Image } from "@stapel/image";
 import { SkinCarousel } from "@stapel/tokens-antd/skin";
 import { useT } from "@stapel/core";
+import type { LinkComponent } from "@stapel/core";
 import { radii, spacing } from "@stapel/tokens";
 import { useListingsRuntime } from "../model/context.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 
+
+/**
+ * The class a linked slide carries.
+ *
+ * `display:block` is the load-bearing half: an inline anchor around a block
+ * image leaves a baseline gap under the picture, which on a grid of tiles is a
+ * visible row of mismatched card heights. The rule itself lives in
+ * `cardTargetCss()`, beside the card's other one-rule-per-defect entries.
+ */
+export const PHOTO_LINK_CLASS = "stapel-listing-photo-link";
+
 /** The default shape of a listing photo box everywhere in this skin. Declared
  * once so a card, a detail hero and a dashboard thumbnail cannot drift into
  * three different crops. */
@@ -151,6 +163,28 @@ export function ListingPhoto(props: ListingPhotoProps): ReactElement {
  * SERP was measured correct on while the desktop card (a still `<img>` inside
  * the anchor, one photo, no dots) was not.
  *
+ * ── …and why each SLIDE may still be one, when a card asks (`href`) ────────
+ *
+ * The rule above is about the STRIP, and it was read as a rule about the
+ * picture. It is not, and the difference was measured: on a 1440px grid the
+ * photo is 267x200 — the largest, most obvious target on the card — and
+ * clicking it did nothing at all. `cursor: auto`, no hover, and the visitor
+ * stayed on the page they were already on. A person who clicks a picture of a
+ * phone is asking to see the phone; there is no reading of that click in which
+ * the right answer is silence.
+ *
+ * So a card may hand this strip its own `href`, and each slide becomes a link
+ * around its picture. What that does NOT do is make the strip a link: the
+ * scroller, its arrows and its dots stay controls, outside every anchor,
+ * because they are what the header's rule is actually protecting. And the
+ * slide links are `tabIndex={-1}` + `aria-hidden`, so a card is still ONE tab
+ * stop and one accessible name — the reading anchor's — rather than one per
+ * photograph.
+ *
+ * A surface that does not pass `href` is byte-identical to before. The phone
+ * SERP passes none: a horizontal swipe is a real gesture there, and it is the
+ * gesture the header's rule was written for.
+ *
  * A listing with no photos still gets one slide, so a row's height does not
  * depend on whether a seller uploaded anything, and a ONE-photo strip gets
  * neither peek nor dots: the sliver of a next slide is an affordance for
@@ -164,10 +198,59 @@ export function ListingPhotoStrip(props: {
   /** The surface's own test id, so a screen holding two kinds of card does
    * not hand a test two elements under one name. */
   readonly testId: string;
+  /**
+   * Where a click on the PICTURE goes — the card's own `href`, when the card
+   * wants its photograph to be part of its target. Omitted, every slide is
+   * inert exactly as it has always been.
+   */
+  readonly href?: string;
+  /** The host's `<Link>`, so the click stays inside the SPA. */
+  readonly linkComponent?: LinkComponent;
 }): ReactElement {
   const t = useT();
   const { images, title } = props;
   const many = images.length > 1;
+
+  /**
+   * One slide, linked or not.
+   *
+   * `aria-hidden` + `tabIndex={-1}`: this is a SECOND way to reach a
+   * destination the card already names, not a second destination. Without it a
+   * grid of twenty-four cards grows twenty-four extra tab stops, each
+   * announcing the same listing the card announced a moment ago.
+   */
+  const slide = (photo: ReactElement, key: string): ReactElement => {
+    if (props.href === undefined) return photo;
+    const Link = props.linkComponent;
+    return Link !== undefined ? (
+      <Link
+        key={key}
+        href={props.href}
+        className={PHOTO_LINK_CLASS}
+        aria-hidden="true"
+        tabIndex={-1}
+        data-testid="listings-photo-link"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+      >
+        {photo}
+      </Link>
+    ) : (
+      <a
+        key={key}
+        href={props.href}
+        className={PHOTO_LINK_CLASS}
+        aria-hidden="true"
+        tabIndex={-1}
+        data-testid="listings-photo-link"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+      >
+        {photo}
+      </a>
+    );
+  };
+
   return (
     <SkinCarousel
       label={t(LISTINGS_I18N_KEYS.cardPhotos)}
@@ -176,24 +259,25 @@ export function ListingPhotoStrip(props: {
       dots={many}
       data-testid={props.testId}
     >
-      {images.length === 0 ? (
-        <ListingPhoto imageRef={undefined} alt={title} />
-      ) : (
-        images.map((reference, index) => (
-          <ListingPhoto
-            key={reference}
-            imageRef={reference}
-            alt={
-              many
-                ? t(LISTINGS_I18N_KEYS.detailPhotoAlt, {
-                    index: index + 1,
-                    total: images.length,
-                  })
-                : title
-            }
-          />
-        ))
-      )}
+      {images.length === 0
+        ? slide(<ListingPhoto imageRef={undefined} alt={title} />, "empty")
+        : images.map((reference, index) =>
+            slide(
+              <ListingPhoto
+                key={reference}
+                imageRef={reference}
+                alt={
+                  many
+                    ? t(LISTINGS_I18N_KEYS.detailPhotoAlt, {
+                        index: index + 1,
+                        total: images.length,
+                      })
+                    : title
+                }
+              />,
+              reference
+            )
+          )}
     </SkinCarousel>
   );
 }

package/src/default/ListingSerpCard.tsx

@@ -99,6 +99,7 @@ import {
   CARD_MEDIA_CLASS,
   CARD_QUERY_CLASS,
   CARD_TARGET_STYLE_HREF,
+  CARD_HOVER_CLASS,
   CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
@@ -247,11 +248,23 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
-        {...(viewed
-          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
-          : {})}
+        // THE PHONE CARD SAYS IT IS A TARGET, TOO (D176). It carried no
+        // hover and no pressed state at all, and the device this card exists
+        // for answers `matchMedia("(hover: hover)")` with false — so a tap
+        // gave no feedback whatever until the next screen arrived. The shared
+        // class is one rule for a pointer that hovers and one for a finger
+        // that presses; `cardTargetCss` states both.
+        className={
+          viewed ? `${CARD_HOVER_CLASS} ${CARD_VIEWED_CLASS}` : CARD_HOVER_CLASS
+        }
+        {...(viewed ? { "data-listing-viewed": "true" } : {})}
         styles={{ body: { minWidth: 0, padding: token.paddingSM } }}
-        style={{ ["--listing-card-focus" as string]: token.colorPrimary }}
+        style={{
+          ["--listing-card-focus" as string]: token.colorPrimary,
+          // The corner the media well is cut to — see `cardTargetCss` (D180).
+          ["--listing-card-radius" as string]: `${String(token.borderRadiusLG)}px`,
+          ["--listing-card-hover-shadow" as string]: token.boxShadowSecondary,
+        }}
       >
         <div className={CARD_QUERY_CLASS}>
           <div className={CARD_FRAME_CLASS} style={{ gap: spacing[3] }}>