@stapel/listings-react 0.23.0 → 0.25.0

package/src/api/types.ts

@@ -123,8 +123,62 @@ export function engagementIds(ids: readonly number[]): readonly number[] {
   return [...seen].sort((a, b) => a - b).slice(0, LISTINGS_ENGAGEMENT_BATCH_LIMIT);
 }
 
-/** `GET /listings/{pk}/` 200 — everything a detail page reads. */
-export type ListingDetail = WithOptionalEngagement<Schemas["ListingDetail"]>;
+/**
+ * The stored-feature columns, restated as the runtime shape.
+ *
+ * `features`, `features_title` and `features_badges` are `JSONField`s (this
+ * file's header, note 2): what reaches the wire is what `build_features_list`
+ * stored, and the OpenAPI union beside them is a DESCRIPTION swapped in by an
+ * extension rather than a filter anything applies. stapel-listings 0.21.3
+ * makes that gap load-bearing: its union spells a badge element with `label`,
+ * `name` and `presentation` REQUIRED, so a row from a server that predates the
+ * contract — the fallback arm `<CardBadges>` exists for, and every row on
+ * every listing published before 0.21.3 — no longer satisfies the generated
+ * type although it is exactly what a card receives.
+ *
+ * So the columns are typed as {@link ListingFeatureDao}, the mirror that says
+ * what a stored row IS, and the contract keys are read off the generated
+ * element instead (`model/cardBadges.ts`) — a rename upstream still breaks the
+ * build, without the generated union refusing the older half of the wire.
+ */
+/**
+ * The badge element the CARD BADGE CONTRACT describes, as the generated schema
+ * spells it (stapel-listings 0.21.3).
+ *
+ * Taken off `Schemas` rather than the relaxed row above, because this is the
+ * one place the contract's own names and readings should still come from the
+ * wire: `model/cardBadges.ts` derives its keys from here, so a rename or a
+ * fifth `presentation` upstream turns this build red.
+ */
+export type ListingCardBadgeElement = Extract<
+  Schemas["ListingCard"]["features_badges"][number],
+  { presentation: unknown }
+>;
+
+type StoredFeatureColumn = "features" | "features_title" | "features_badges";
+
+/**
+ * A stored row AS IT ARRIVES: every key of the mirror, none of them promised.
+ *
+ * `slug` is required on {@link ListingFeatureDao} because a row without one is
+ * unusable — and a JSONField ships one anyway when the projection misses it,
+ * which `featureFromDao` reports rather than papering over with a synthesized
+ * index. `asFeatureDaoList` is the single narrowing point between the two.
+ */
+export type ListingFeatureRow = Partial<ListingFeatureDao>;
+
+type WithStoredFeatures<Row> = Omit<Row, StoredFeatureColumn> & {
+  readonly [K in Extract<keyof Row, StoredFeatureColumn>]: readonly ListingFeatureRow[];
+};
+
+/** `GET /listings/{pk}/` 200 — everything a detail page reads.
+ *
+ * `category_id` is nullable here because the CONTRACT says so as of
+ * stapel-listings 0.21.4 — a draft may exist before its category is chosen —
+ * so the pair reads the generated type rather than relaxing it by hand. */
+export type ListingDetail = WithStoredFeatures<
+  WithOptionalEngagement<Schemas["ListingDetail"]>
+>;
 
 /**
  * One row of a card list (`GET /listings/`, `GET /listings/my/favorites/`) —
@@ -158,8 +212,8 @@ type WithOptionalPrecision<Row extends { geo_precision_km?: number }> = Omit<
 > &
   Partial<Pick<Schemas["ListingCard"], "geo_precision_km">>;
 
-export type ListingCard = WithOptionalPrecision<
-  WithOptionalEngagement<Schemas["ListingCard"]>
+export type ListingCard = WithStoredFeatures<
+  WithOptionalPrecision<WithOptionalEngagement<Schemas["ListingCard"]>>
 >;
 
 /** `POST /listings/` request+response and `POST /{pk}/save-draft/` response —
@@ -216,8 +270,8 @@ export type PaginatedListingCards = Omit<
  *    tab keyed off them is a column of blank rows. `myListingTitle` /
  *    `myListingPrice` (`model/mine.ts`) are the one place the fallback lives.
  */
-export type MyListingCard = WithOptionalPrecision<
-  WithOptionalEngagement<Schemas["MyListingCard"]>
+export type MyListingCard = WithStoredFeatures<
+  WithOptionalPrecision<WithOptionalEngagement<Schemas["MyListingCard"]>>
 >;
 
 /** The keyset envelope `GET /listings/my/listings/` comes back in — the same

package/src/default/CardBadges.tsx

@@ -0,0 +1,105 @@
+/**
+ * A card's badge line, drawn against the CARD BADGE CONTRACT when the server
+ * speaks it and exactly as it draws today when it does not.
+ *
+ * The contract itself — the five keys, the four presentations, and the
+ * measured "Brick · 3 · 9" that earned it — is `model/cardBadges.ts`.
+ * This file is only the two arms:
+ *
+ *  - **the contract arm.** Each element already carries everything a reader
+ *    needs (its name, its unit, its resolved copy, and the server's decision
+ *    about which of them to print), so the text comes from `cardBadgeText`
+ *    and nothing here reaches for a category, a formatter or an option table;
+ *  - **the fallback arm.** No element declares a `presentation`, which means
+ *    a backend older than stapel-listings 0.21.3 — so the row goes through
+ *    `@stapel/attributes-react`'s `<FeatureBadges>` off the stored DAO's own
+ *    config, byte-identical to the release before this one.
+ *
+ * One component, called by all three card surfaces, for the same reason
+ * `CardTarget` is one function: three cards each deciding what a badge says
+ * is three places for the bare numbers to come back.
+ */
+import type { ReactElement } from "react";
+import { Flex, Tag, Typography } from "antd";
+import { SkinTheme } from "@stapel/tokens-antd/skin";
+import { useI18n } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { FeatureBadges } from "@stapel/attributes-react/default";
+import type { ListingFeatureDao } from "../api/types.js";
+import type { CardBadgeRow } from "../model/cardBadges.js";
+import { cardBadgeTexts, hasCardBadgeContract } from "../model/cardBadges.js";
+import { featuresDtoFromDaoList, featuresFromDaoList } from "../model/features.js";
+import type { FeatureCopySource } from "../model/features.js";
+
+export interface CardBadgesProps {
+  /** The stored projection — `features_badges` or `features_title`. */
+  readonly rows: readonly ListingFeatureDao[];
+  /** The category's option table, where the surface has one. Used by the
+   * FALLBACK arm only: a contract element carries its own resolved copy. */
+  readonly copy: FeatureCopySource;
+  /**
+   * `"badges"` draws tags (the card's badge strip); `"line"` draws one
+   * dot-separated run of secondary text (the seller's own spec line under
+   * the title, which is already a line on every surface).
+   */
+  readonly variant: "badges" | "line";
+  readonly testId?: string;
+}
+
+/** The separator of a spec line — the one every classified uses. */
+const LINE_SEPARATOR = " · ";
+
+export function CardBadges(props: CardBadgesProps): ReactElement | null {
+  const { locale } = useI18n();
+  const rows = props.rows as readonly CardBadgeRow[];
+
+  if (rows.length === 0) return null;
+
+  if (hasCardBadgeContract(rows)) {
+    const printed = cardBadgeTexts(rows, locale);
+    if (printed.length === 0) return null;
+    if (props.variant === "line") {
+      return (
+        <span data-testid={props.testId ?? "listings-card-badges"}>
+          {printed.map((one) => one.text).join(LINE_SEPARATOR)}
+        </span>
+      );
+    }
+    return (
+      <SkinTheme surface="bare">
+        <Flex gap={spacing[1]} wrap data-testid={props.testId ?? "listings-card-badges"}>
+          {printed.map((one) => (
+            <Tag key={one.slug} data-testid={`listings-card-badge-${one.slug}`}>
+              {one.text}
+            </Tag>
+          ))}
+        </Flex>
+      </SkinTheme>
+    );
+  }
+
+  // The older backend. Exactly what shipped before the contract existed.
+  const views = featuresFromDaoList(rows, props.copy);
+  if (views.length === 0) return null;
+  return (
+    <FeatureBadges
+      features={views.map((view) => view.feature)}
+      values={featuresDtoFromDaoList(rows)}
+    />
+  );
+}
+
+/** The spec line under a card's title, wrapped in the secondary, truncating
+ * text every surface already draws it in. */
+export function CardSpecLine(props: {
+  readonly rows: readonly ListingFeatureDao[];
+  readonly copy: FeatureCopySource;
+  readonly testId: string;
+}): ReactElement | null {
+  if (props.rows.length === 0) return null;
+  return (
+    <Typography.Text type="secondary" ellipsis data-testid={props.testId}>
+      <CardBadges rows={props.rows} copy={props.copy} variant="line" testId={`${props.testId}-text`} />
+    </Typography.Text>
+  );
+}

package/src/default/ListingCard.tsx

@@ -116,15 +116,15 @@ import {
 import { useActionGate, useT } from "@stapel/core";
 import type { LinkComponent, SignInCtaProp } from "@stapel/core";
 import { 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 { asFeatureDaoList } 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 { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { CardBadges, CardSpecLine } from "./CardBadges.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
 import { HeartIcon } from "./icons.js";
 import { SignInLink } from "./SignInLink.js";
@@ -539,13 +539,13 @@ export function ListingCard(props: ListingCardProps): ReactElement {
   const badgeDaos = asFeatureDaoList(listing.features_badges);
   // The category's own option table, when the surface has it: a stored
   // `select` carries no table of its own, so without this a badge prints the
-  // storage slug. Absent on a mixed grid, which is why it is optional.
+  // storage slug. Absent on a mixed grid, which is why it is optional. Read
+  // by the FALLBACK arm of `<CardBadges>` only — an element that speaks the
+  // card badge contract carries its own resolved copy.
   const copy: FeatureCopySource =
     props.categoryFeatures !== undefined
       ? { categoryFeatures: props.categoryFeatures }
       : {};
-  const badgeFeatures = featuresFromDaoList(badgeDaos, copy);
-  const badgeValues = featuresDtoFromDaoList(badgeDaos);
   const titleDaos = asFeatureDaoList(listing.features_title);
 
   const status = listing.status === undefined ? undefined : lifecycleCaption(listing.status);
@@ -610,23 +610,9 @@ export function ListingCard(props: ListingCardProps): ReactElement {
 
       {/* The title features are a stored projection too — the seller's
           "1.5 TB, black" line, already ordered by the server. */}
-      {titleDaos.length > 0 ? (
-        <Typography.Text type="secondary" ellipsis>
-          <FeatureBadges
-            features={featuresFromDaoList(titleDaos, copy).map(
-              (view) => view.feature
-            )}
-            values={featuresDtoFromDaoList(titleDaos)}
-          />
-        </Typography.Text>
-      ) : null}
+      <CardSpecLine rows={titleDaos} copy={copy} testId="listings-card-specs" />
 
-      {badgeFeatures.length > 0 ? (
-        <FeatureBadges
-          features={badgeFeatures.map((view) => view.feature)}
-          values={badgeValues}
-        />
-      ) : null}
+      <CardBadges rows={badgeDaos} copy={copy} variant="badges" />
 
       {/* ONE line, and it truncates (D185). Measured on a live 1440px feed:
           a two-part city-and-district name wrapped, the text block grew

package/src/default/ListingDetailPane.tsx

@@ -69,13 +69,14 @@ import {
 } from "@stapel/core";
 import type { SignInCta } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
-import { FeatureValueList } from "@stapel/attributes-react/default";
-import { formatFeatureValue, isRedactedValue } from "@stapel/attributes-react";
+import { isRedactedValue } from "@stapel/attributes-react";
 import { useListingDetail } from "../headless/ListingDetail.js";
 import { useListingActions } from "../headless/ListingActions.js";
 import { asFeatureDaoList, featureValuesForDisplay } from "../model/features.js";
+import { formatSpecValue } from "../model/featureText.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
+import { ListingSpecColumns, ListingSpecList } from "./ListingSpecList.js";
 import { SignInLink } from "./SignInLink.js";
 import { HeartIcon } from "./icons.js";
 import { ListingPhoto } from "./ListingPhoto.js";
@@ -338,7 +339,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                       // leaked identifier would be read out loud.
                       .filter((view) => !isRedactedValue(view.value))
                       .map((view) =>
-                        formatFeatureValue(view.feature, view.value, { t, locale })
+                        formatSpecValue(view.feature, view.value, { t, locale })
                       )
                       .filter((text): text is string => text !== undefined)
                       .join(" · ")}
@@ -548,47 +549,22 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                 ? { categoryFeatures: props.categoryFeatures }
                 : {}
             );
-            /* Two spec columns in the split, split by ROW COUNT and not by
-               `<FeatureValueList>` — the halves are cut HERE so the category's
-               declaration order survives: the first (larger) half fills the
-               left list, and the table reads top-to-bottom, left column
-               first, exactly as the one-column table read. */
-            const specHalf = Math.ceil(bag.features.length / 2);
+            /* Two spec columns in the split — a grid of whole ROWS, cut by
+               row count so the category's declaration order survives: the
+               first (larger) half fills the left list and the page reads
+               top-to-bottom, left column first, exactly as the one-column
+               list reads. The label is never a column of its own; see
+               `<ListingSpecList>` for the shape and why the table went. */
+            const specFeatures = bag.features.map((view) => view.feature);
             const specs =
               bag.features.length === 0 ? (
                 <Typography.Text type="secondary" data-testid="listings-detail-no-specs">
                   {t(LISTINGS_I18N_KEYS.detailNoSpecs)}
                 </Typography.Text>
               ) : split ? (
-                <div
-                  data-testid="listings-detail-specs-split"
-                  style={{
-                    display: "grid",
-                    gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
-                    gap: spacing[4],
-                    alignItems: "start",
-                  }}
-                >
-                  <FeatureValueList
-                    features={bag.features
-                      .slice(0, specHalf)
-                      .map((view) => view.feature)}
-                    values={specValues}
-                  />
-                  {bag.features.length > specHalf ? (
-                    <FeatureValueList
-                      features={bag.features
-                        .slice(specHalf)
-                        .map((view) => view.feature)}
-                      values={specValues}
-                    />
-                  ) : null}
-                </div>
+                <ListingSpecColumns features={specFeatures} values={specValues} />
               ) : (
-                <FeatureValueList
-                  features={bag.features.map((view) => view.feature)}
-                  values={specValues}
-                />
+                <ListingSpecList features={specFeatures} values={specValues} />
               );
 
             const specsSection = (

package/src/default/ListingPhoto.tsx

@@ -30,6 +30,12 @@ import { useT } from "@stapel/core";
 import type { LinkComponent } from "@stapel/core";
 import { radii, spacing } from "@stapel/tokens";
 import { useListingsRuntime } from "../model/context.js";
+import {
+  CARD_GALLERY_CLASS,
+  CARD_GALLERY_STYLE_HREF,
+  cardGalleryCss,
+  useCardGallery,
+} from "./cardGallery.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 
 
@@ -210,6 +216,9 @@ export function ListingPhotoStrip(props: {
   const t = useT();
   const { images, title } = props;
   const many = images.length > 1;
+  // Hover-scrub and swipe. Inert for a one-photo strip; see `cardGallery.ts`
+  // for the two gates and why the keyboard path is untouched.
+  const gallery = useCardGallery(images.length);
 
   /**
    * One slide, linked or not.
@@ -252,32 +261,51 @@ export function ListingPhotoStrip(props: {
   };
 
   return (
-    <SkinCarousel
-      label={t(LISTINGS_I18N_KEYS.cardPhotos)}
-      aspectRatio={LISTING_PHOTO_ASPECT}
-      peek={many}
-      dots={many}
-      data-testid={props.testId}
+    <div
+      ref={gallery.ref}
+      className={CARD_GALLERY_CLASS}
+      data-testid={`${props.testId}-gallery`}
+      data-gallery-photos={String(images.length)}
+      data-gallery-active={String(gallery.active)}
+      data-scrubbing={String(gallery.scrubbing)}
+      data-analytics="none"
+      data-analytics-reason="a look, not an outcome — scrubbing photographs navigates nowhere and changes no record"
+      onPointerMove={gallery.onPointerMove}
+      onPointerDown={gallery.onPointerDown}
+      onPointerUp={gallery.onPointerUp}
+      onPointerCancel={gallery.onPointerCancel}
+      onPointerLeave={gallery.onPointerLeave}
     >
-      {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>
+      <style href={CARD_GALLERY_STYLE_HREF} precedence="default">
+        {cardGalleryCss()}
+      </style>
+      <SkinCarousel
+        label={t(LISTINGS_I18N_KEYS.cardPhotos)}
+        aspectRatio={LISTING_PHOTO_ASPECT}
+        peek={many}
+        dots={many}
+        data-testid={props.testId}
+      >
+        {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>
+    </div>
   );
 }

package/src/default/ListingSerpCard.tsx

@@ -79,13 +79,8 @@ import { SkinTheme } from "@stapel/tokens-antd/skin";
 import type { SignInCta } from "@stapel/core";
 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 { asFeatureDaoList } from "../model/features.js";
 import type { FeatureCopySource } from "../model/features.js";
 import { lifecycleCaption } from "../model/status.js";
 import { isListingViewed } from "../model/engagement.js";
@@ -93,6 +88,7 @@ import { useEngagedListing } from "../headless/Engagement.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { PriceTrendIcon } from "./icons.js";
 import { FavoriteHeart } from "./favorite.js";
+import { CardBadges, CardSpecLine } from "./CardBadges.js";
 import {
   CARD_FRAME_CLASS,
   CARD_MAIN_CLASS,
@@ -188,8 +184,6 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
     props.categoryFeatures !== undefined
       ? { categoryFeatures: props.categoryFeatures }
       : {};
-  const badgeFeatures = featuresFromDaoList(badgeDaos, copy);
-  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 =
@@ -346,27 +340,15 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
                       >
                         {props.specsLine}
                       </Typography.Text>
-                    ) : titleDaos.length > 0 ? (
-                      <Typography.Text
-                        type="secondary"
-                        ellipsis
-                        data-testid="listings-serp-specs"
-                      >
-                        <FeatureBadges
-                          features={featuresFromDaoList(titleDaos, copy).map(
-                            (view) => view.feature,
-                          )}
-                          values={featuresDtoFromDaoList(titleDaos)}
-                        />
-                      </Typography.Text>
-                    ) : null}
-
-                    {badgeFeatures.length > 0 ? (
-                      <FeatureBadges
-                        features={badgeFeatures.map((view) => view.feature)}
-                        values={badgeValues}
+                    ) : (
+                      <CardSpecLine
+                        rows={titleDaos}
+                        copy={copy}
+                        testId="listings-serp-specs"
                       />
-                    ) : null}
+                    )}
+
+                    <CardBadges rows={badgeDaos} copy={copy} variant="badges" />
                   </CardTarget>
 
                   {/* Outside the anchor, both of them: a seller line usually holds