@stapel/listings-react 0.22.1 → 0.24.0

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

package/src/default/ListingSpecList.tsx

@@ -0,0 +1,195 @@
+/**
+ * The listing page's spec rows ("Characteristics"), as SENTENCES.
+ *
+ * ── What was on screen, and why a table was the wrong shape ───────────────
+ *
+ * The list was `<Descriptions column={1}>`: a real two-column table, label
+ * cell beside value cell. On a phone — and in the split layout's half-width
+ * left column — the value cell is narrow, so a long answer ("Trim level",
+ * a full trim name, a two-line address) wrapped INSIDE it and stacked under
+ * itself in a column a third of the page wide, beside acres of empty label
+ * gutter. A spec row is not tabular data that a reader scans down one axis;
+ * it is a short question and its answer, and it reads as a line of text.
+ *
+ * So the label is an inline `<span>`, muted, and the value follows it in the
+ * SAME text flow. A long value now wraps as a paragraph — full measure,
+ * hanging under the label — and a short one costs one line instead of a row
+ * of a table.
+ *
+ * ── The two-column grid that survives is a grid of ROWS ───────────────────
+ *
+ * The split layout still puts two columns of spec rows side by side on a wide
+ * screen, because a forty-row list under a photograph is a scroll nobody
+ * finishes. What is gone is the label being its own COLUMN: the columns hold
+ * whole rows, cut by row count so the category's declaration order still
+ * reads top-to-bottom, left column first. `<ListingSpecColumns>` is that cut,
+ * kept here beside the row it cuts.
+ *
+ * ── Units and digits ─────────────────────────────────────────────────────
+ *
+ * Every value goes through `formatSpecValue` rather than the shared
+ * `formatFeatureValue`: same answer, typeset — the unit appended and the
+ * digits grouped by the reader's locale. `model/featureText.ts` says where
+ * the unit comes from and why there is no `unit` key to read it from.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import { Typography, theme as antdTheme } from "antd";
+import { SkinTheme } from "@stapel/tokens-antd/skin";
+import { useI18n, useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import {
+  ATTRIBUTES_I18N_KEYS,
+  featureName,
+  featureType,
+  isRedactedValue,
+  isValuePresent,
+  isValueVerified,
+} from "@stapel/attributes-react";
+import type { FeatureDef, FeatureValueDto } from "@stapel/attributes-react";
+import { formatSpecValue } from "../model/featureText.js";
+
+/** The class one spec row carries. */
+export const SPEC_ROW_CLASS = "stapel-listing-spec-row";
+/** The class the row's inline label carries. */
+export const SPEC_LABEL_CLASS = "stapel-listing-spec-label";
+/** The `href` the hoisted spec stylesheet is deduplicated by. */
+export const SPEC_STYLE_HREF = "stapel-listings-spec";
+
+/**
+ * The rules an inline style cannot express — the label's own colour is set
+ * per-instance as a custom property so ONE hoisted copy serves either theme.
+ *
+ * `display: inline` on the label is the whole fix and is stated rather than
+ * inherited: antd's `<Text>` renders a `<span>`, but a skin that retunes it
+ * to a block would silently put the table back.
+ */
+export function specListCss(): string {
+  return [
+    // A paragraph, not a table row. `margin: 0` because the gap between rows
+    // is the list's, so a row can be lifted into a grid cell unchanged.
+    `.${SPEC_ROW_CLASS}{margin:0;min-inline-size:0;overflow-wrap:anywhere}`,
+    `.${SPEC_LABEL_CLASS}{display:inline;color:var(--listing-spec-label)}`,
+    // The one space between the question and the answer, owned by the label
+    // rather than written as a text node — a `{" "}` between two JSX elements
+    // is the kind of whitespace a formatter deletes.
+    `.${SPEC_LABEL_CLASS}::after{content:"\\00a0"}`,
+  ].join("");
+}
+
+export interface ListingSpecListProps {
+  /** The category's features, in the order they are declared. */
+  readonly features: readonly FeatureDef[];
+  /** The DISPLAY envelope — redacted stubs included, which is what makes a
+   * withheld row keep its place. */
+  readonly values: Readonly<Record<string, FeatureValueDto>>;
+  /** The surface's own test id, so a split page holding two columns of these
+   * does not hand a test two elements under one name. */
+  readonly testId?: string;
+  readonly style?: CSSProperties;
+}
+
+/**
+ * A withheld value's row: what the system OBSERVED, and nothing more — the
+ * same three states `@stapel/attributes-react` prints, said with its own
+ * copy keys so the two lists cannot drift into two different sentences.
+ */
+function redactedText(dto: FeatureValueDto | undefined, t: (key: string) => string): string {
+  if (!isValuePresent(dto)) return t(ATTRIBUTES_I18N_KEYS.valueNotSet);
+  if (isValueVerified(dto)) return t(ATTRIBUTES_I18N_KEYS.valueVerified);
+  return t(ATTRIBUTES_I18N_KEYS.valueProvided);
+}
+
+export function ListingSpecList(props: ListingSpecListProps): ReactElement {
+  const t = useT();
+  const { locale } = useI18n();
+  const { token } = antdTheme.useToken();
+
+  // A `header` is a section caption in a FORM, not a value: it has none, and
+  // a spec table that printed one would print "not specified" under it.
+  const rows = props.features.filter((feature) => featureType(feature) !== "header");
+
+  return (
+    <SkinTheme surface="bare">
+      <style href={SPEC_STYLE_HREF} precedence="default">
+        {specListCss()}
+      </style>
+      <div
+        data-testid={props.testId ?? "listings-spec-list"}
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: spacing[1],
+          minWidth: 0,
+          ["--listing-spec-label" as string]: token.colorTextSecondary,
+          ...props.style,
+        }}
+      >
+        {rows.map((feature) => {
+          const dto = props.values[feature.slug];
+          const redacted = isRedactedValue(dto);
+          const text = redacted
+            ? redactedText(dto, t)
+            : (formatSpecValue(feature, dto, { t, locale }) ??
+              t(
+                dto === undefined || featureType(feature) === undefined
+                  ? ATTRIBUTES_I18N_KEYS.valueNotSet
+                  : ATTRIBUTES_I18N_KEYS.valueUnreadable
+              ));
+          return (
+            <p
+              key={feature.slug}
+              className={SPEC_ROW_CLASS}
+              data-testid={`listings-spec-row-${feature.slug}`}
+            >
+              <Typography.Text
+                type="secondary"
+                className={SPEC_LABEL_CLASS}
+                data-testid={`listings-spec-label-${feature.slug}`}
+              >
+                {featureName(feature)}
+              </Typography.Text>
+              <span data-testid={`listings-spec-value-${feature.slug}`}>{text}</span>
+            </p>
+          );
+        })}
+      </div>
+    </SkinTheme>
+  );
+}
+
+/**
+ * The same rows in TWO columns on a wide screen — a grid of whole rows, cut
+ * by row count so the category's declaration order still reads top-to-bottom,
+ * left column first.
+ *
+ * The cut is here rather than inside the list because a CSS `columns` rule
+ * would break a wrapped paragraph across the column boundary, which is
+ * exactly the defect the paragraph shape was adopted to avoid.
+ */
+export function ListingSpecColumns(props: ListingSpecListProps): ReactElement {
+  const half = Math.ceil(props.features.length / 2);
+  return (
+    <div
+      data-testid={props.testId ?? "listings-detail-specs-split"}
+      style={{
+        display: "grid",
+        gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
+        gap: spacing[4],
+        alignItems: "start",
+      }}
+    >
+      <ListingSpecList
+        features={props.features.slice(0, half)}
+        values={props.values}
+        testId="listings-spec-list"
+      />
+      {props.features.length > half ? (
+        <ListingSpecList
+          features={props.features.slice(half)}
+          values={props.values}
+          testId="listings-spec-list-second"
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/default/MyListingsPane.tsx

@@ -119,6 +119,19 @@ function myListingsCss(): string {
   ].join("");
 }
 
+/**
+ * The row `listingHref` is called with as its second argument — the same
+ * object the row renders from, with `title` guaranteed present.
+ *
+ * `MyListingCard.title` is the PUBLISHED field and is `""`/absent on a
+ * listing nobody has ever submitted (`model/mine.ts`'s header) — but
+ * {@link RowLink} never calls `href` for such a row (`neverSubmitted` bails
+ * out first), so every row that reaches a `listingHref` call has a real
+ * title. The cast below is that guarantee made structural rather than
+ * re-checked at each call site.
+ */
+export type MyListingHrefRow = MyListingCard & { title: string };
+
 /**
  * The row's title and thumbnail, as a link to the listing's own page when the
  * host has one.
@@ -141,7 +154,7 @@ function myListingsCss(): string {
  */
 function RowLink(props: {
   listing: MyListingCard;
-  href: ((id: number) => string) | undefined;
+  href: ((id: number, row: MyListingHrefRow) => string) | undefined;
   linkComponent: LinkComponent | undefined;
   children: ReactNode;
   testId: string;
@@ -149,7 +162,7 @@ function RowLink(props: {
 }): ReactElement {
   const { href, listing } = props;
   if (href === undefined || neverSubmitted(listing)) return <>{props.children}</>;
-  const target = href(listing.id);
+  const target = href(listing.id, listing as MyListingHrefRow);
   const Link = props.linkComponent;
   const shared = {
     href: target,
@@ -171,7 +184,7 @@ function MyListingRow(props: {
   listing: MyListingCard;
   onEdit?: ((id: number) => void) | undefined;
   onAskRemove: (id: number) => void;
-  listingHref?: ((id: number) => string) | undefined;
+  listingHref?: ((id: number, row: MyListingHrefRow) => string) | undefined;
   linkComponent?: LinkComponent | undefined;
 }): ReactElement {
   const t = useT();
@@ -353,7 +366,12 @@ export interface MyListingsPaneProps extends ThemeModeProp, SignInCtaProp {
   readonly onEdit?: (id: number) => void;
   /**
    * Where a listing's own page lives, given its id — `(id) => \`/l/${id}\``
-   * for a storefront.
+   * for a storefront that only needs the id, or
+   * `(id, row) => \`/l/${id}-${slugify(row.title)}\`` for one whose routes
+   * carry a slug. The second argument is the same {@link MyListingCard} the
+   * row renders from, narrowed to {@link MyListingHrefRow} (`title`
+   * guaranteed present) — a host that ignores it keeps the id-only form
+   * working exactly as before.
    *
    * Absent, the row's title and thumbnail are plain text and a picture, which
    * is what this pane shipped: a live cabinet held zero links to a listing,
@@ -362,7 +380,7 @@ export interface MyListingsPaneProps extends ThemeModeProp, SignInCtaProp {
    * have no public page has nothing to link TO — but it is now a decision the
    * host makes rather than one this file made for everyone.
    */
-  readonly listingHref?: (id: number) => string;
+  readonly listingHref?: (id: number, row: MyListingHrefRow) => string;
   /**
    * The router's link, so those two targets are client-side navigations. A
    * plain `<a href>` otherwise — right-clickable and correct, just a full page