@stapel/listings-react 0.9.0 → 0.10.0

package/src/default/ListingFeedCard.tsx

@@ -0,0 +1,232 @@
+/**
+ * `<ListingFeedCard>` — the borderless card of a phone home feed (refs §1).
+ *
+ * ── What "borderless" is actually doing ───────────────────────────────────
+ *
+ * `<ListingCard>` and `<ListingSerpCard>` are antd `Card`s: a painted surface
+ * with a border, which is what makes one result read as one object next to
+ * another. A two-column feed is a different picture. Twenty bordered boxes on
+ * a 390px screen is twenty frames and forty vertical lines, and the photos —
+ * the only thing anyone is actually looking at — end up as small pictures
+ * inside chrome. So this card has no surface of its own: the photo is the
+ * card, the three lines under it sit on the page's own ground, and the RHYTHM
+ * of the grid is what separates one from the next. That is the ref, and it is
+ * also why this is a third component rather than a `bordered={false}` on the
+ * first: nothing else about the layout survives the change either.
+ *
+ * ── The heart is over the photo here, and only here ───────────────────────
+ *
+ * `<ListingCard>` argues at length that the heart belongs in a row UNDER the
+ * card rather than floating on the photograph, because a blocked favourite
+ * states its reason as text and there is nowhere to put a sentence on top of a
+ * picture. That argument is correct and this card does not repeat its
+ * conclusion, for a reason it states rather than hides: a 2-column feed tile
+ * has no line to spare. A full row of "Sign in to save this" under every one
+ * of twenty tiles is not twenty pieces of help — it is the feed.
+ *
+ * The fleet already has the mechanism for exactly this and it is not "hide the
+ * reason": `GateReasonScopeContext` / `<PaneGate>` pool identical reasons and
+ * render each ONCE for everything inside the scope, with every control's
+ * `aria-describedby` still pointing at that single copy. **A container drawing
+ * a feed should wrap `<FeedGrid>` in a `<PaneGate>`.** Unscoped, the reason
+ * still renders — over the photo, visible, never behind a hover — because a
+ * reason a person cannot read is the one outcome the doctrine forbids.
+ *
+ * ── Two lines of title, and then it stops ─────────────────────────────────
+ *
+ * A feed tile is roughly 170px wide. A three-line title pushes the price below
+ * the fold of the row and makes the grid ragged; a one-line ellipsis throws
+ * away the half of a listing's name that distinguishes it from the one beside
+ * it. Two lines, clamped, is the ref's answer and the only one that keeps the
+ * price on the same y as its neighbour's.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Flex, Typography } from "antd";
+import { SkinTheme } from "@stapel/tokens-antd/skin";
+import { useT } from "@stapel/core";
+import { radii, spacing } from "@stapel/tokens";
+import type { ListingCard as ListingCardData } from "../api/types.js";
+import { lifecycleCaption } from "../model/status.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { FavoriteHeart } from "./favorite.js";
+import {
+  CARD_TARGET_STYLE_HREF,
+  CardTarget,
+  cardTargetCss,
+} from "./ListingCard.js";
+import type { ListingCardOpenProps } from "./ListingCard.js";
+import { ListingPhoto } from "./ListingPhoto.js";
+import { ListingPrice } from "./ListingPrice.js";
+import type { ThemeModeProp } from "./types.js";
+
+/** Lines of title a tile draws before it clips. See the file header. */
+const TITLE_LINES = 2;
+
+/** The class the clamped title carries, for {@link feedCardCss}. */
+export const FEED_TITLE_CLASS = "stapel-listing-feed-title";
+
+/** The `href` the hoisted feed stylesheet is deduplicated by. */
+export const FEED_CARD_STYLE_HREF = "stapel-listings-feed-card";
+
+/**
+ * The clamp, as a real CSS rule rather than an inline style.
+ *
+ * `-webkit-line-clamp` and `-webkit-box-orient` are the two declarations that
+ * do not survive the trip through an inline style object: React's serializer
+ * and every DOM implementation that is not a browser drop them silently, so a
+ * tile written that way clamps in Chrome, does not clamp in a test, and
+ * nothing anywhere says which. A hoisted sheet keeps one copy for the document
+ * and makes the rule something a test can read.
+ */
+export function feedCardCss(): string {
+  return (
+    `.${FEED_TITLE_CLASS}{display:-webkit-box;-webkit-box-orient:vertical;` +
+    `-webkit-line-clamp:${String(TITLE_LINES)};overflow:hidden}`
+  );
+}
+
+/** The tile. `position: relative` is what the heart and the badge overlay are
+ * pinned to; `minWidth: 0` keeps a long word inside its grid track. */
+const TILE: CSSProperties = { position: "relative", minWidth: 0 };
+
+/** Pinned to the photo's leading corner: the container's own marking. */
+const BADGE: CSSProperties = {
+  position: "absolute",
+  insetBlockStart: spacing[2],
+  insetInlineStart: spacing[2],
+};
+
+/** Pinned to the photo's trailing corner. `alignItems: flex-end` so the
+ * pooled-or-not reason, when there is one, stacks under the heart against the
+ * same edge rather than pushing it inwards. */
+const HEART: CSSProperties = {
+  position: "absolute",
+  insetBlockStart: spacing[2],
+  insetInlineEnd: spacing[2],
+  alignItems: "flex-end",
+};
+
+export interface ListingFeedCardBaseProps extends ThemeModeProp {
+  readonly listing: ListingCardData;
+  /**
+   * Drawn over the photo's leading corner — "New", "In stock", a promotion
+   * marking. A SLOT rather than a string: what earns an overlay on a feed is a
+   * deployment's decision, and DSA Art. 26 marking belongs to whichever pair
+   * received the fact.
+   */
+  readonly badgeOverlay?: ReactNode;
+  /** Hide the favourite entirely — for a surface where it makes no sense.
+   * NOT a way to hide it from visitors. */
+  readonly showFavorite?: boolean;
+}
+
+export type ListingFeedCardProps = ListingFeedCardBaseProps & ListingCardOpenProps;
+
+export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
+  const t = useT();
+  const { listing } = props;
+  const status =
+    listing.status === undefined ? undefined : lifecycleCaption(listing.status);
+  const title = listing.title ?? "";
+  const targetLabel =
+    title.length > 0 ? title : t(LISTINGS_I18N_KEYS.cardUntitled);
+
+  return (
+    <SkinTheme
+      surface="bare"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <style href={CARD_TARGET_STYLE_HREF} precedence="default">
+        {cardTargetCss()}
+      </style>
+      <style href={FEED_CARD_STYLE_HREF} precedence="default">
+        {feedCardCss()}
+      </style>
+      <div
+        style={TILE}
+        data-testid="listings-feed-card"
+        data-listing-id={listing.id}
+        {...(status !== undefined
+          ? { "data-listing-status": status.status }
+          : {})}
+      >
+        {/* One anchor over the whole tile. The photo is a still `<img>`, so
+            unlike the SERP card's swipeable strip it is safe inside a link —
+            and on a feed the picture IS the click. */}
+        <CardTarget
+          {...openProps(props)}
+          listingId={listing.id}
+          label={targetLabel}
+          testId="listings-feed-open"
+          bodyTestId="listings-feed-body"
+        >
+          <Flex vertical gap={spacing[1]}>
+            <ListingPhoto
+              imageRef={listing.images?.[0]}
+              alt={title.length > 0 ? title : String(listing.id)}
+              style={{ borderRadius: radii.lg }}
+            />
+
+            {/* Title before price: on a feed a person is browsing, not
+                comparing — the ref's order, and the reverse of the SERP's. */}
+            <Typography.Text
+              className={FEED_TITLE_CLASS}
+              data-testid="listings-feed-title"
+            >
+              {title}
+            </Typography.Text>
+
+            <Typography.Text strong data-testid="listings-feed-price">
+              <ListingPrice
+                amount={listing.price}
+                {...(listing.currency !== undefined
+                  ? { currency: listing.currency }
+                  : {})}
+              />
+            </Typography.Text>
+
+            {listing.location_label !== undefined &&
+            listing.location_label.length > 0 ? (
+              <Typography.Text
+                type="secondary"
+                ellipsis
+                data-testid="listings-feed-location"
+              >
+                {listing.location_label}
+              </Typography.Text>
+            ) : null}
+          </Flex>
+        </CardTarget>
+
+        {props.badgeOverlay !== undefined && (
+          <div style={BADGE} data-testid="listings-feed-badge">
+            {props.badgeOverlay}
+          </div>
+        )}
+
+        {/* Outside the anchor — a button inside a link is neither valid HTML
+            nor operable — and pinned rather than stacked. See the header. */}
+        {props.showFavorite === false ? null : (
+          <FavoriteHeart
+            listingId={listing.id}
+            favorited={listing.is_favorited}
+            testId="listings-feed-favorite"
+            style={HEART}
+          />
+        )}
+      </div>
+    </SkinTheme>
+  );
+}
+
+/** The three-armed open union, narrowed out of this card's own props — see
+ * `<ListingSerpCard>`'s copy for why it is picked rather than spread. */
+function openProps(props: ListingFeedCardProps): ListingCardOpenProps {
+  if (props.href !== undefined) {
+    return props.linkComponent !== undefined
+      ? { href: props.href, linkComponent: props.linkComponent }
+      : { href: props.href };
+  }
+  if (props.onOpen !== undefined) return { onOpen: props.onOpen };
+  return {};
+}

package/src/default/ListingSerpCard.tsx

@@ -0,0 +1,374 @@
+/**
+ * `<ListingSerpCard>` — the one-column result card of a phone SERP.
+ *
+ * `<ListingCard>` is the GRID card: a photo, a price, a title and a place,
+ * sized so twenty-four of them tile a desktop catalogue. This is the other
+ * shape a classified needs and the one the mobile refs are drawn to (refs §3):
+ * one card per row, the full width of the screen, a swipeable photo strip, and
+ * a column of actions down the right-hand side. They are two components rather
+ * than a `variant` prop for the reason the fleet keeps writing down — a mode
+ * switch produces one component nobody can photograph either arm of, and here
+ * the two arms differ in reading ORDER, not only in size.
+ *
+ * ── The price is first, and it is the biggest thing on the card ────────────
+ *
+ * On a grid card the photo carries the layout. On a one-column result the
+ * photo is already full-bleed above the text, so the first LINE is where the
+ * eye lands — and on a classified that line is the price. Title at regular
+ * weight underneath it, the seller's own spec line muted under that. This is
+ * the ref's order and it is also the order the fleet's own storefront review
+ * asked for: a person scanning a SERP is comparing prices, not reading names.
+ *
+ * ── Why the photo strip is OUTSIDE the anchor ─────────────────────────────
+ *
+ * `<ListingCard>` puts its photo inside the card's anchor, because a still
+ * `<img>` inside a link is just a bigger link. A `<SkinCarousel>` is not: it
+ * 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. Putting
+ * the strip in the anchor would mean every attempt to look at photo two
+ * navigated to the listing — the defect that makes phone galleries unusable.
+ *
+ * So the strip sits above the anchor as a sibling, exactly as the heart sits
+ * below it as a sibling, and for the same class of reason: a link may not
+ * contain a control, and a swipeable strip is a control. The anchor still
+ * covers the four things that identify the listing — price, title, specs,
+ * badges — so the card opens from everything a person reads.
+ *
+ * ── The two slots, and what they are honestly for ─────────────────────────
+ *
+ * `sellerSlot` is the seller's name and rating. It is a SLOT because a rating
+ * aggregate belongs to `@stapel/reviews-react` and this pair does not import
+ * another L2 pair; the container is the seam. **The caveat a host must know:**
+ * `<RatingBadge>` FETCHES — one request per card. On a page of twenty results
+ * that is twenty requests for a decoration. A container drawing this in a list
+ * should render the name plus a bare `<Rate>` from an aggregate the row
+ * already carries, and render nothing at all when the row carries none. It
+ * lives outside the anchor because a seller's name is usually a link to the
+ * seller, and a link inside a link is neither valid nor operable.
+ *
+ * `actionsRail` is the vertical column at the trailing edge — "call", "write"
+ * — filled by the container from `@stapel/chat-react` and from whatever the
+ * deployment uses for a phone number. The pair supplies the COLUMN and the
+ * favourite heart at the end of it, and nothing else: this package has no
+ * conversation and no telephone number, and the search projection carries no
+ * phone (gap G-2's neighbour, recorded in the wave spec §4).
+ *
+ * ── The price trend is a seam over data that does not exist yet ───────────
+ *
+ * `priceTrend` renders the ref's "was 1 800 000 ₽ ↓". The search projection
+ * carries no price history — no `price_was`, no direction — so nothing on a
+ * live SERP fills this today (wave gap **G-2**). It ships anyway, and the
+ * demos show it against fixture data, because the alternative is a card that
+ * has to be re-laid-out the day the projection grows the field. The seam is
+ * the honest half; the missing data is written down rather than faked.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Card, Flex, Typography, theme as antdTheme } from "antd";
+import { SkinCarousel, SkinTheme } from "@stapel/tokens-antd/skin";
+import { useT } from "@stapel/core";
+import { fontSize, spacing } from "@stapel/tokens";
+import { FeatureBadges } from "@stapel/attributes-react/default";
+import type { ListingCard as ListingCardData } from "../api/types.js";
+import {
+  asFeatureDaoList,
+  featuresDtoFromDaoList,
+  featuresFromDaoList,
+} from "../model/features.js";
+import { lifecycleCaption } from "../model/status.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { PriceTrendIcon } from "./icons.js";
+import { FavoriteHeart } from "./favorite.js";
+import {
+  CARD_TARGET_STYLE_HREF,
+  CardTarget,
+  cardTargetCss,
+} from "./ListingCard.js";
+import type { ListingCardOpenProps } from "./ListingCard.js";
+import { LISTING_PHOTO_ASPECT, ListingPhoto } from "./ListingPhoto.js";
+import { ListingPrice } from "./ListingPrice.js";
+import type { ThemeModeProp } from "./types.js";
+
+/**
+ * A price that moved, as the ref draws it: the old figure struck through and
+ * an arrow saying which way.
+ *
+ * `oldPrice` is a decimal STRING in the listing's own currency — the same
+ * dialect `Listing.price` speaks — so it is formatted by the same
+ * `<ListingPrice>` and never by a template literal.
+ */
+export interface ListingPriceTrend {
+  /** The previous asking price, as the wire spells money: a decimal string. */
+  readonly oldPrice: string;
+  /** Which way it moved. `"down"` is the one a classified shouts about. */
+  readonly direction: "down" | "up";
+}
+
+export interface ListingSerpCardBaseProps extends ThemeModeProp {
+  readonly listing: ListingCardData;
+  /**
+   * The seller's own one-line summary — "Petrol 1.5 (147 hp), robot, front".
+   *
+   * A STRING the host derived, not a projection this card reads: the ref's
+   * spec line is a deployment's editorial choice about which features belong
+   * on a result and in what order, and that is a decision no library can take
+   * for a category it has never seen. When the host has no opinion the card
+   * falls back to the row's `features_title` — the projection's own summary is
+   * a better default line than an empty one (§83: the default skin does the
+   * right thing before the host wires anything).
+   */
+  readonly specsLine?: string;
+  /** See the file header — a seam over data the projection does not carry. */
+  readonly priceTrend?: ListingPriceTrend;
+  /** The seller's name and rating. See the file header for the per-card fetch
+   * caveat a container has to avoid. */
+  readonly sellerSlot?: ReactNode;
+  /** The vertical action column at the trailing edge — call, write. The
+   * favourite heart is added at its end by this component. */
+  readonly actionsRail?: ReactNode;
+  /** Extra chrome above the price (a `promoted` tag from search — DSA Art. 26
+   * marking belongs to the pair that receives it). */
+  readonly badge?: ReactNode;
+  /** Hide the favourite entirely — for a surface where it makes no sense (the
+   * owner's own listings). NOT a way to hide it from visitors. */
+  readonly showFavorite?: boolean;
+}
+
+export type ListingSerpCardProps = ListingSerpCardBaseProps & ListingCardOpenProps;
+
+/** The trailing column. Fixed width contribution: it must not take room from
+ * the text as the actions grow. */
+const RAIL: CSSProperties = { flex: "0 0 auto" };
+
+/** The reading column. `minWidth: 0` so a long unbroken word cannot push the
+ * rail off the card. */
+const BODY: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
+
+export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
+  const t = useT();
+  const { listing, priceTrend } = props;
+  const { token } = antdTheme.useToken();
+
+  const badgeDaos = asFeatureDaoList(listing.features_badges);
+  const badgeFeatures = featuresFromDaoList(badgeDaos);
+  const badgeValues = featuresDtoFromDaoList(badgeDaos);
+  // The fallback spec line when the host derived none: the row's own
+  // `features_title` projection, exactly the line `ListingCard` draws.
+  const titleDaos =
+    props.specsLine !== undefined && props.specsLine.length > 0
+      ? []
+      : asFeatureDaoList(listing.features_title);
+
+  const status =
+    listing.status === undefined ? undefined : lifecycleCaption(listing.status);
+
+  const title = listing.title ?? "";
+  const targetLabel =
+    title.length > 0 ? title : t(LISTINGS_I18N_KEYS.cardUntitled);
+  const photos = listing.images ?? [];
+  const currency =
+    listing.currency !== undefined ? { currency: listing.currency } : {};
+
+  // A one-photo strip gets neither a peek nor dots: the sliver of a next slide
+  // is an affordance for something that is there, and on a single photo it is
+  // just a strip of dead space at the trailing edge (`SkinCarousel` says the
+  // same thing from its own side).
+  const many = photos.length > 1;
+
+  const rail =
+    props.actionsRail !== undefined || props.showFavorite !== false ? (
+      <Flex
+        vertical
+        align="flex-end"
+        gap={spacing[2]}
+        style={RAIL}
+        data-testid="listings-serp-actions"
+      >
+        {props.actionsRail}
+        {props.showFavorite === false ? null : (
+          <FavoriteHeart
+            listingId={listing.id}
+            favorited={listing.is_favorited}
+            testId="listings-serp-favorite"
+          />
+        )}
+      </Flex>
+    ) : null;
+
+  return (
+    <SkinTheme
+      surface="bare"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <style href={CARD_TARGET_STYLE_HREF} precedence="default">
+        {cardTargetCss()}
+      </style>
+      <Card
+        size="small"
+        data-testid="listings-serp-card"
+        data-listing-id={listing.id}
+        {...(status !== undefined
+          ? { "data-listing-status": status.status }
+          : {})}
+        styles={{ body: { minWidth: 0, padding: token.paddingSM } }}
+        style={{ ["--listing-card-focus" as string]: token.colorPrimary }}
+      >
+        <Flex vertical gap={spacing[3]}>
+          {/* The strip is a SIBLING of the anchor, never a child — see the
+              file header. A listing with no photos still gets one slide, so
+              the card's height does not depend on whether a seller uploaded
+              anything. */}
+          <SkinCarousel
+            label={t(LISTINGS_I18N_KEYS.cardPhotos)}
+            aspectRatio={LISTING_PHOTO_ASPECT}
+            peek={many}
+            dots={many}
+            data-testid="listings-serp-photos"
+          >
+            {photos.length === 0 ? (
+              <ListingPhoto
+                imageRef={undefined}
+                alt={title.length > 0 ? title : String(listing.id)}
+              />
+            ) : (
+              photos.map((reference, index) => (
+                <ListingPhoto
+                  key={reference}
+                  imageRef={reference}
+                  alt={t(LISTINGS_I18N_KEYS.detailPhotoAlt, {
+                    index: index + 1,
+                    total: photos.length,
+                  })}
+                />
+              ))
+            )}
+          </SkinCarousel>
+
+          <Flex gap={spacing[3]} align="flex-start">
+            <Flex vertical gap={spacing[1]} style={BODY}>
+              <CardTarget
+                {...openProps(props)}
+                listingId={listing.id}
+                label={targetLabel}
+                testId="listings-serp-open"
+                bodyTestId="listings-serp-body"
+              >
+                {props.badge}
+
+                {/* PRICE FIRST, and loud. `fontSize.xl` rather than an antd
+                    heading: this is a price, not a section title, and it must
+                    not enter the document outline of a page holding twenty of
+                    them. */}
+                <Flex align="center" gap={spacing[2]} wrap>
+                  <Typography.Text
+                    strong
+                    style={{ fontSize: fontSize.xl.fontSize }}
+                    data-testid="listings-serp-price"
+                  >
+                    <ListingPrice amount={listing.price} {...currency} />
+                  </Typography.Text>
+                  {priceTrend !== undefined && (
+                    <PriceTrendIcon
+                      direction={priceTrend.direction}
+                      label={t(
+                        priceTrend.direction === "down"
+                          ? LISTINGS_I18N_KEYS.cardPriceDropped
+                          : LISTINGS_I18N_KEYS.cardPriceRaised
+                      )}
+                    />
+                  )}
+                </Flex>
+
+                {priceTrend !== undefined && (
+                  <Flex
+                    align="baseline"
+                    gap={spacing[1]}
+                    data-testid="listings-serp-old-price"
+                  >
+                    {/* The strike-through is what a sighted reader sees and
+                        nothing a screen reader announces, so the word is on
+                        the line too rather than left to the styling. */}
+                    <Typography.Text type="secondary">
+                      {t(LISTINGS_I18N_KEYS.cardPriceWas)}
+                    </Typography.Text>
+                    <Typography.Text type="secondary" delete>
+                      <ListingPrice amount={priceTrend.oldPrice} {...currency} />
+                    </Typography.Text>
+                  </Flex>
+                )}
+
+                <Typography.Text data-testid="listings-serp-title">
+                  {title}
+                </Typography.Text>
+
+                {props.specsLine !== undefined && props.specsLine.length > 0 ? (
+                  <Typography.Text
+                    type="secondary"
+                    ellipsis
+                    data-testid="listings-serp-specs"
+                  >
+                    {props.specsLine}
+                  </Typography.Text>
+                ) : titleDaos.length > 0 ? (
+                  <Typography.Text
+                    type="secondary"
+                    ellipsis
+                    data-testid="listings-serp-specs"
+                  >
+                    <FeatureBadges
+                      features={featuresFromDaoList(titleDaos).map(
+                        (view) => view.feature,
+                      )}
+                      values={featuresDtoFromDaoList(titleDaos)}
+                    />
+                  </Typography.Text>
+                ) : null}
+
+                {badgeFeatures.length > 0 ? (
+                  <FeatureBadges
+                    features={badgeFeatures.map((view) => view.feature)}
+                    values={badgeValues}
+                  />
+                ) : null}
+              </CardTarget>
+
+              {/* Outside the anchor, both of them: a seller line usually holds
+                  a link to the seller, and the place is the last thing read
+                  rather than part of what the card is called. */}
+              {props.sellerSlot ?? null}
+
+              {listing.location_label !== undefined &&
+              listing.location_label.length > 0 ? (
+                <Typography.Text
+                  type="secondary"
+                  data-testid="listings-serp-location"
+                >
+                  {listing.location_label}
+                </Typography.Text>
+              ) : null}
+            </Flex>
+
+            {rail}
+          </Flex>
+        </Flex>
+      </Card>
+    </SkinTheme>
+  );
+}
+
+/**
+ * The three-armed open union, narrowed back out of this card's own props.
+ *
+ * Spreading `props` straight into `<CardTarget>` would hand it `listing`,
+ * `sellerSlot` and the rest as DOM attributes on the arms that render a plain
+ * `<a>`; picking the union's members explicitly keeps the anchor clean and
+ * keeps exactly one of the three arms reachable.
+ */
+function openProps(props: ListingSerpCardProps): ListingCardOpenProps {
+  if (props.href !== undefined) {
+    return props.linkComponent !== undefined
+      ? { href: props.href, linkComponent: props.linkComponent }
+      : { href: props.href };
+  }
+  if (props.onOpen !== undefined) return { onOpen: props.onOpen };
+  return {};
+}