@stapel/listings-react 0.18.2 → 0.20.0

package/src/default/ListingDetailPane.tsx

@@ -51,7 +51,7 @@
  * and the default `"column"` renders exactly what existing hosts already get.
  */
 import type { ReactElement, ReactNode } from "react";
-import { Descriptions, Divider, Flex, Typography } from "antd";
+import { Descriptions, Divider, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
 import {
   ErrorAlert,
@@ -175,6 +175,7 @@ export interface ListingDetailPaneProps
 export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const t = useT();
   const { locale } = useI18n();
+  const { token } = antdTheme.useToken();
   const bag = useListingDetail(props.id, {
     ...(props.viewerId !== undefined ? { viewerId: props.viewerId } : {}),
     ...(props.categoryFeatures !== undefined
@@ -190,10 +191,19 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const split = props.layout === "split";
 
   const favoriteLabel = t(
-    bag.isFavorited === true
+    bag.isFavorited
       ? LISTINGS_I18N_KEYS.cardFavoriteRemove
       : LISTINGS_I18N_KEYS.cardFavoriteAdd
   );
+  // Saved is a SOLID accent shape; not-saved (and `is_favorited: null`, which
+  // is "nobody asked", not "no") is the outline. The bag flips it on the
+  // gesture and rolls it back if the write fails — see `useListingDetail`.
+  const heartIcon = (
+    <HeartIcon
+      filled={bag.isFavorited}
+      {...(bag.isFavorited ? { color: token.colorPrimary } : {})}
+    />
+  );
 
   return (
     <SkinTheme
@@ -334,6 +344,33 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                       .join(" · ")}
                   </Typography.Text>
                 ) : null}
+
+                {/* How many people opened it — the listing's own meta line,
+                    under the title, where a reader looks for how much company
+                    they have. It spent one release as a row of the
+                    `<Descriptions>` below (walker D106): wedged between the
+                    colour attribute and the location row, two screens down,
+                    read as a PROPERTY OF THE GOODS rather than a fact about
+                    the page. A view count is not a characteristic of a phone.
+
+                    `bag.viewCount` is `undefined` when the response carries
+                    no such field, and then there is no line at all — never a
+                    zero standing in for an absence. There is no favourite
+                    count beside it because the wire has none: the schema
+                    carries `is_favorited`, a per-reader boolean, and no
+                    aggregate anywhere (asserted in test/engagementState). */}
+                {bag.viewCount !== undefined ? (
+                  <Typography.Text
+                    type="secondary"
+                    data-testid="listings-detail-meta"
+                    style={{ display: "block" }}
+                  >
+                    {t(LISTINGS_I18N_KEYS.detailViews)}:{" "}
+                    <span data-testid="listings-detail-views">
+                      {bag.viewCount}
+                    </span>
+                  </Typography.Text>
+                ) : null}
               </>
             );
 
@@ -416,9 +453,10 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                         aria-disabled
                         {...bind}
                         aria-label={favoriteLabel}
-                        aria-pressed={bag.isFavorited === true}
-                        icon={<HeartIcon filled={bag.isFavorited === true} />}
+                        aria-pressed={bag.isFavorited}
+                        icon={heartIcon}
                         data-testid="listings-detail-favorite"
+                        data-favorited={String(bag.isFavorited)}
                         data-analytics="none"
                         data-analytics-reason="business action — host app wraps with its own tracked()"
                         onClick={bag.toggleFavorite}
@@ -435,15 +473,13 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     >
                       {(bind) => (
                         <Button
-                          disabled={bind.disabled}
-                          data-disabled-reason="the enclosing <GatedControl> renders the gate's reason beside this button"
-                          {...(bind["aria-describedby"] !== undefined
-                            ? { "aria-describedby": bind["aria-describedby"] }
-                            : {})}
+                          // See `<ListingCard>`: the binding, spread whole.
+                          {...bind}
                           aria-label={favoriteLabel}
-                          aria-pressed={bag.isFavorited === true}
-                          icon={<HeartIcon filled={bag.isFavorited === true} />}
+                          aria-pressed={bag.isFavorited}
+                          icon={heartIcon}
                           data-testid="listings-detail-favorite"
+                          data-favorited={String(bag.isFavorited)}
                           data-analytics="none"
                           data-analytics-reason="business action — host app wraps with its own tracked()"
                           onClick={bag.toggleFavorite}
@@ -470,14 +506,26 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               </Flex>
             );
 
-            const actionError =
-              actions.error !== undefined && actions.error !== null ? (
+            const actionError = (
+              <>
+                {actions.error !== undefined && actions.error !== null ? (
+                  <ErrorAlert
+                    testId="listings-detail-action-error"
+                    thrown={actions.error}
+                    variant="inline"
+                  />
+                ) : null}
+                {/* A save that did not save. The heart has already rolled
+                    back to the state the tap started from — that is the
+                    honest picture and a silent one, so the sentence goes
+                    beside it. `ErrorAlert` renders nothing for nothing. */}
                 <ErrorAlert
-                  testId="listings-detail-action-error"
-                  thrown={actions.error}
+                  testId="listings-detail-favorite-error"
+                  thrown={bag.favoriteError}
                   variant="inline"
                 />
-              ) : null;
+              </>
+            );
 
             const description = (
               <>
@@ -565,26 +613,35 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               </>
             );
 
-            const meta = (
+            const hasStock = listing.stock_quantity != null;
+            const hasPlace =
+              listing.location_label !== undefined &&
+              listing.location_label.length > 0;
+
+            // Both rows absent draws an empty table, which the view count used
+            // to hide by almost always being there. Nothing is nothing.
+            const meta = !hasStock && !hasPlace ? null : (
               <Descriptions size="small" column={1}>
                 {/* Label cell and value cell, which is what a `<Descriptions>`
                     row IS: the label key carries no `{count}` (it did, and the
                     page printed the placeholder), the quantity is the value. */}
-                {listing.stock_quantity != null ? (
+                {hasStock ? (
                   <Descriptions.Item label={t(LISTINGS_I18N_KEYS.detailStock)}>
                     <span data-testid="listings-detail-stock">
                       {listing.stock_quantity}
                     </span>
                   </Descriptions.Item>
                 ) : null}
-                {listing.location_label !== undefined &&
-                listing.location_label.length > 0 ? (
+                {hasPlace ? (
                   <Descriptions.Item
                     label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}
                   >
                     {listing.location_label}
                   </Descriptions.Item>
                 ) : null}
+                {/* The view count used to be a third row here. It is a fact
+                    about the PAGE, not a property of the goods, so it now
+                    reads on the meta line under the title — see `heading`. */}
               </Descriptions>
             );
 

package/src/default/ListingFeedCard.tsx

@@ -24,13 +24,27 @@
  * 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.
+ * The answer this card ships with is the INTERACTION DISCLOSURE the grid card
+ * and the SERP card were given in the desktop and mobile fix packs, and it is
+ * this card's DEFAULT rather than an opt-in — a two-column tile is the one
+ * surface in the pair with no line to put a sentence on, so a standing volume
+ * here has to overprint the photograph to exist at all.
+ *
+ * That default is a fix, not a preference. Measured on a live home feed: this
+ * was the last surface still printing "Sign in to do this" as standing copy,
+ * over the picture, under every tile — and the heart under it was html-
+ * `disabled`, so the one gesture that could have replaced the caption was
+ * swallowed by the control. Both halves are gone: nothing stands in the tile,
+ * and a tap on the heart discloses the reason and the container's sign-in
+ * door (`signIn`) while a visually-hidden copy keeps the refusal in the
+ * accessibility tree. A host that genuinely wants the standing sentence back
+ * asks for it by name with `blockedReason="text"`.
+ *
+ * `GateReasonScopeContext` / `<PaneGate>` remain the answer for the STANDING
+ * arm: they 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 in that arm should wrap
+ * `<FeedGrid>` in a `<PaneGate>`.
  *
  * ── Two lines of title, and then it stops ─────────────────────────────────
  *
@@ -43,14 +57,18 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Flex, Typography } from "antd";
 import { SkinTheme } from "@stapel/tokens-antd/skin";
+import type { SignInCta } from "@stapel/core";
 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 { isListingViewed } from "../model/engagement.js";
+import { useEngagedListing } from "../headless/Engagement.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { FavoriteHeart } from "./favorite.js";
 import {
   CARD_TARGET_STYLE_HREF,
+  CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
 } from "./ListingCard.js";
@@ -118,18 +136,32 @@ export interface ListingFeedCardBaseProps extends ThemeModeProp {
   /** Hide the favourite entirely — for a surface where it makes no sense.
    * NOT a way to hide it from visitors. */
   readonly showFavorite?: boolean;
+  /**
+   * How loudly a blocked heart states its refusal. **`"popover"` by default
+   * on this card, unlike the other two** — a feed tile has no line to print a
+   * sentence on, so the standing arm can only overprint the photograph. See
+   * the file header for the measurement that made it the default.
+   */
+  readonly blockedReason?: "text" | "popover";
+  /** The container's sign-in door, rendered INSIDE the disclosure. Absent:
+   * the disclosure holds the reason alone. */
+  readonly signIn?: SignInCta;
 }
 
 export type ListingFeedCardProps = ListingFeedCardBaseProps & ListingCardOpenProps;
 
 export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
   const t = useT();
-  const { listing } = props;
+  // See `<ListingCard>`: the scope's overlay over the row, or the row. This
+  // is the surface it matters most on — a home feed is drawn from search.
+  const listing = useEngagedListing(props.listing);
   const status =
     listing.status === undefined ? undefined : lifecycleCaption(listing.status);
   const title = listing.title ?? "";
   const targetLabel =
     title.length > 0 ? title : t(LISTINGS_I18N_KEYS.cardUntitled);
+  // Already seen — `false` for every response that carries no such field.
+  const viewed = isListingViewed(listing);
 
   return (
     <SkinTheme
@@ -149,6 +181,9 @@ export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        {...(viewed
+          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
+          : {})}
       >
         {/* 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 —
@@ -211,6 +246,8 @@ export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
             listingId={listing.id}
             favorited={listing.is_favorited}
             testId="listings-feed-favorite"
+            blockedReason={props.blockedReason ?? "popover"}
+            {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
             style={HEART}
           />
         )}

package/src/default/ListingPrice.tsx

@@ -37,8 +37,19 @@ import {
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 
 export interface ListingPriceProps {
-  /** The amount as the wire spells it — a decimal string. */
-  readonly amount: string | undefined;
+  /**
+   * The amount as the wire spells it — a decimal string, or `null` for a
+   * listing that carries no price at all.
+   *
+   * `null` is in the TYPE since stapel-listings 0.17 spelled it in the
+   * schema (`price?: string | null`, D51: a blank price stays null
+   * server-side). It was always in the DATA — `hasAmount` below has guarded
+   * for it from the start, with a comment saying the serializer hands it
+   * through an unguarded `string | undefined`. Now the type says what the
+   * runtime already knew, and the guard stops being a defence against its
+   * own signature.
+   */
+  readonly amount: string | null | undefined;
   /** The code the amount is quoted in (`Listing.currency`). */
   readonly currency?: string | undefined;
 }

package/src/default/ListingSerpCard.tsx

@@ -88,6 +88,8 @@ import {
 } from "../model/features.js";
 import type { FeatureCopySource } from "../model/features.js";
 import { lifecycleCaption } from "../model/status.js";
+import { isListingViewed } from "../model/engagement.js";
+import { useEngagedListing } from "../headless/Engagement.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { PriceTrendIcon } from "./icons.js";
 import { FavoriteHeart } from "./favorite.js";
@@ -97,6 +99,7 @@ import {
   CARD_MEDIA_CLASS,
   CARD_QUERY_CLASS,
   CARD_TARGET_STYLE_HREF,
+  CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
 } from "./ListingCard.js";
@@ -172,7 +175,9 @@ const BODY: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
 
 export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   const t = useT();
-  const { listing, priceTrend } = props;
+  const { priceTrend } = props;
+  // See `<ListingCard>`: the scope's overlay over the row, or the row.
+  const listing = useEngagedListing(props.listing);
   const { token } = antdTheme.useToken();
 
   const badgeDaos = asFeatureDaoList(listing.features_badges);
@@ -200,6 +205,8 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   const photos = listing.images ?? [];
   const currency =
     listing.currency !== undefined ? { currency: listing.currency } : {};
+  // Already seen — `false` for every response that carries no such field.
+  const viewed = isListingViewed(listing);
 
   const rail =
     props.actionsRail !== undefined || props.showFavorite !== false ? (
@@ -240,6 +247,9 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        {...(viewed
+          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
+          : {})}
         styles={{ body: { minWidth: 0, padding: token.paddingSM } }}
         style={{ ["--listing-card-focus" as string]: token.colorPrimary }}
       >

package/src/default/favorite.tsx

@@ -26,8 +26,9 @@
  * list or a grid of these cards should wrap it in one.
  */
 import type { CSSProperties, ReactElement } from "react";
+import { theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
-import { GatedControl } from "@stapel/tokens-antd/skin";
+import { ErrorAlert, GatedControl } from "@stapel/tokens-antd/skin";
 import type { SignInCta } from "@stapel/core";
 import { useActionGate, useT } from "@stapel/core";
 import { useFavoriteToggle } from "../headless/Favorites.js";
@@ -70,22 +71,49 @@ export interface FavoriteHeartProps {
  * (`signIn`) is the surface's business, not this control's — a disabled antd
  * button fires no pointer events, so a tooltip here would be a reason nobody
  * could read on any device (`stapel/no-tooltip-in-skin`).
+ *
+ * ── It is never html-`disabled`, in either volume ─────────────────────────
+ *
+ * `aria-disabled` plus a live handler, always. The refusal happens on
+ * ACTIVATION — `useFavoriteToggle().toggle` is a no-op while the gate is
+ * blocked, so the click cannot write anything — and that is the only shape of
+ * refusal a person can interrogate. A `disabled` DOM button is inert: it
+ * takes no focus, receives no pointer events, and swallows the very tap that
+ * was supposed to explain it. Measured on a phone: a signed-out visitor's
+ * heart produced no toast, no reason and no navigation, and on a touch device
+ * there is no hover to fall back on.
  */
 export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   const t = useT();
+  const { token } = antdTheme.useToken();
   const favorite = useFavoriteToggle(props.listingId, props.favorited);
   const label = t(
     favorite.favorited
       ? LISTINGS_I18N_KEYS.cardFavoriteRemove
       : LISTINGS_I18N_KEYS.cardFavoriteAdd
   );
+  // Saved is a SOLID accent shape, not-saved is the outline. `is_favorited:
+  // null` — an anonymous read's "nobody asked" — resolves to not-saved in the
+  // bag, so it draws the outline and never a third look of its own.
+  const icon = (
+    <HeartIcon
+      filled={favorite.favorited}
+      {...(favorite.favorited ? { color: token.colorPrimary } : {})}
+    />
+  );
   // The RESOLVED sentence, not the gate's key — `useActionGate` is the one
   // place a blocked reason becomes words in this fleet.
   const reason = useActionGate(favorite.gate).reason;
+  // A failed save, stated where the heart is. The rollback already put the
+  // icon back; this says why it went back.
+  const failure = (
+    <ErrorAlert
+      testId={`${props.testId}-error`}
+      thrown={favorite.error}
+      variant="inline"
+    />
+  );
   if (props.blockedReason === "popover" && reason !== undefined) {
-    // `aria-disabled`, never `disabled`: the gate already refuses the action
-    // (`toggle` is a no-op while blocked), and an html-disabled button
-    // swallows the hover, the focus and the tap the disclosure opens on.
     return (
       <GateReasonPopover
         reason={reason}
@@ -105,7 +133,7 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
             data-analytics="none"
             data-analytics-reason="business action — host app wraps with its own tracked()"
             onClick={favorite.toggle}
-            icon={<HeartIcon filled={favorite.favorited} />}
+            icon={icon}
             {...(props.style !== undefined ? { style: props.style } : {})}
           />
         )}
@@ -120,22 +148,22 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
       {...(props.style !== undefined ? { style: props.style } : {})}
     >
       {(bind) => (
-        <Button
-          shape="circle"
-          disabled={bind.disabled}
-          data-disabled-reason="the enclosing <GatedControl> renders the gate's reason beside this button"
-          {...(bind["aria-describedby"] !== undefined
-            ? { "aria-describedby": bind["aria-describedby"] }
-            : {})}
-          aria-label={label}
-          aria-pressed={favorite.favorited}
-          data-testid={props.testId}
-          data-favorited={String(favorite.favorited)}
-          data-analytics="none"
-          data-analytics-reason="business action — host app wraps with its own tracked()"
-          onClick={favorite.toggle}
-          icon={<HeartIcon filled={favorite.favorited} />}
-        />
+        <>
+          <Button
+            shape="circle"
+            // See `<ListingCard>`: the substrate's binding, spread whole.
+            {...bind}
+            aria-label={label}
+            aria-pressed={favorite.favorited}
+            data-testid={props.testId}
+            data-favorited={String(favorite.favorited)}
+            data-analytics="none"
+            data-analytics-reason="business action — host app wraps with its own tracked()"
+            onClick={favorite.toggle}
+            icon={icon}
+          />
+          {failure}
+        </>
       )}
     </GatedControl>
   );

package/src/default/icons.tsx

@@ -13,14 +13,32 @@
  */
 import type { ReactElement } from "react";
 
-export function HeartIcon(props: { filled: boolean }): ReactElement {
+export interface HeartIconProps {
+  /** Saved: the glyph is a solid shape rather than an outline. THE state a
+   * person reads off a card, so it is the one prop this icon has. */
+  readonly filled: boolean;
+  /**
+   * The accent a SAVED heart is painted in — an antd theme token the caller
+   * resolved (`token.colorPrimary`), never a literal.
+   *
+   * The icon stays `currentColor` by default, which is what keeps it
+   * theme-neutral in every other state; this is the one place a colour is
+   * warranted, because "filled" and "outline" of the same neutral grey is a
+   * difference a person reads at a glance on a mock-up and misses entirely on
+   * a 170px feed tile in daylight.
+   */
+  readonly color?: string;
+}
+
+export function HeartIcon(props: HeartIconProps): ReactElement {
+  const paint = props.color ?? "currentColor";
   return (
     <svg
       width="16"
       height="16"
       viewBox="0 0 24 24"
-      fill={props.filled ? "currentColor" : "none"}
-      stroke="currentColor"
+      fill={props.filled ? paint : "none"}
+      stroke={paint}
       strokeWidth="2"
       strokeLinecap="round"
       strokeLinejoin="round"

package/src/default/index.ts

@@ -39,6 +39,10 @@ export {
   // threshold (and for a test that measures it). See `<ListingCard>`'s header.
   LISTING_CARD_ROW_MIN,
   LISTING_CARD_ROW_MEDIA,
+  // The already-seen mark, for a container that wants to dim its own chrome
+  // on the same rule (and for a test that reads it). All three cards take it.
+  CARD_VIEWED_CLASS,
+  LISTING_VIEWED_OPACITY,
 } from "./ListingCard.js";
 export type {
   ListingCardProps,