@stapel/listings-react 0.9.0 → 0.10.0

package/src/default/favorite.tsx

@@ -0,0 +1,91 @@
+/**
+ * The favourite heart, once — the control every card surface in this pair
+ * draws and none of them may draw differently.
+ *
+ * `<ListingCard>` had it inline, and the two phone cards added in the mobile
+ * wave (`<ListingSerpCard>`, `<ListingFeedCard>`) need exactly the same thing:
+ * the same hook, the same gate, the same `aria-pressed`, the same refusal
+ * printed as text rather than as a tooltip. Three copies of that is three
+ * places for the anonymous arm to drift apart in, and the anonymous arm is
+ * most of a storefront's traffic. So it lives here and the surfaces differ
+ * only in WHERE they put it.
+ *
+ * This module is deliberately NOT re-exported from `src/default/index.ts`: it
+ * is how this pair's own cards are built, not a control a host composes with.
+ * A host that wants a favourite button outside a card has `useFavoriteToggle`.
+ *
+ * ── The refusal, and why a grid needs a scope ──────────────────────────────
+ *
+ * `<GatedControl>` prints the gate's reason beside the control and wires
+ * `aria-describedby` to it. That is right for ONE card and wrong for forty:
+ * the same sentence forty times is the loudest thing on a results page. The
+ * substrate already answers this — `GateReasonScopeContext` (a `<PaneGate>`
+ * provides one) pools identical reasons and renders each once, and a
+ * `GatedControl` inside a scope renders no text of its own while keeping the
+ * `aria-describedby` pointed at the scope's single copy. A container drawing a
+ * list or a grid of these cards should wrap it in one.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import { Button } from "antd";
+import { GatedControl } from "@stapel/tokens-antd/skin";
+import { useT } from "@stapel/core";
+import { useFavoriteToggle } from "../headless/Favorites.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { HeartIcon } from "./icons.js";
+
+export interface FavoriteHeartProps {
+  readonly listingId: number;
+  /** `is_favorited` off the row. `null` is the third state — a search hit
+   * never says whether you saved it — and reads as "not saved". */
+  readonly favorited: boolean | null | undefined;
+  /** Test id of the button; the gate wrapper takes `${testId}-gate`. */
+  readonly testId: string;
+  /** `"inline"` puts the reason beside the heart, `"stack"` (default) under
+   * it — the choice belongs to the surface, which knows its own geometry. */
+  readonly layout?: "stack" | "inline";
+  readonly style?: CSSProperties;
+}
+
+/**
+ * The heart and its refusal. It is NEVER hidden from a visitor: it is blocked,
+ * the reason is on the page as ordinary text, and the container's sign-in door
+ * (`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`).
+ */
+export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
+  const t = useT();
+  const favorite = useFavoriteToggle(props.listingId, props.favorited);
+  const label = t(
+    favorite.favorited
+      ? LISTINGS_I18N_KEYS.cardFavoriteRemove
+      : LISTINGS_I18N_KEYS.cardFavoriteAdd
+  );
+  return (
+    <GatedControl
+      gate={favorite.gate}
+      testId={`${props.testId}-gate`}
+      {...(props.layout !== undefined ? { layout: props.layout } : {})}
+      {...(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} />}
+        />
+      )}
+    </GatedControl>
+  );
+}

package/src/default/icons.tsx

@@ -1,13 +1,15 @@
 /**
- * One inline glyph: the favourite heart, filled and outlined.
+ * The pair's inline glyphs: the favourite heart, and the price-trend arrow.
  *
  * No `@ant-design/icons` dependency — the house convention (profiles-react's
  * `icons.tsx`, shell-react's icon registry): a plain monochrome
  * `currentColor` SVG, so it inherits the theme instead of carrying a colour
  * of its own, and the pair stays one package lighter.
  *
- * `aria-hidden` on both: the button that holds them carries the label, and a
- * glyph announced beside its own label reads the action twice.
+ * `aria-hidden` on the heart: the button that holds it carries the label, and
+ * a glyph announced beside its own label reads the action twice. The TREND
+ * arrow is the opposite case — it is the only thing on the line saying which
+ * way the price moved, so it takes a name from the caller and is announced.
  */
 import type { ReactElement } from "react";
 
@@ -29,3 +31,35 @@ export function HeartIcon(props: { filled: boolean }): ReactElement {
     </svg>
   );
 }
+
+/**
+ * Which way the asking price moved — an arrow, and a NAME for it.
+ *
+ * The arrow is the whole message ("this got cheaper"), so unlike the heart it
+ * is not `aria-hidden`: it carries `role="img"` and the sentence the caller
+ * resolved from its own key registry. A glyph that means something and is
+ * hidden from assistive tech means nothing to the people who need it stated.
+ */
+export function PriceTrendIcon(props: {
+  direction: "down" | "up";
+  label: string;
+}): ReactElement {
+  const down = props.direction === "down";
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-label={props.label}
+    >
+      <path d={down ? "M12 5v14" : "M12 19V5"} />
+      <path d={down ? "M6 13l6 6 6-6" : "M6 11l6-6 6 6"} />
+    </svg>
+  );
+}

package/src/default/index.ts

@@ -1,7 +1,17 @@
 /**
- * `@stapel/listings-react/default` — the antd skin: the card another pair
+ * `@stapel/listings-react/default` — the antd skin: the cards another pair
  * renders, the listing page, the composer and the seller's dashboard.
  *
+ * ── Three cards, because a classified has three shelves ────────────────────
+ *
+ * `ListingCard` is the grid card (a bordered surface, photo-led, twenty-four
+ * to a desktop catalogue). `ListingSerpCard` is the phone result row (one per
+ * line, a swipeable photo strip, PRICE first, a vertical action rail).
+ * `ListingFeedCard` + `FeedGrid` are the home feed (borderless, two across,
+ * the photo carried on the page's own ground). They are three components and
+ * not one with a `variant`, because they differ in READING ORDER and in what
+ * may live inside the card's anchor — not merely in size.
+ *
  * A separate entry point (the convention every pair's `/default` follows) so
  * a host rendering its own visuals over the bags never pulls `antd` into its
  * bundle.
@@ -30,6 +40,19 @@ export type {
   ListingCardOpenProps,
   ListingCardBlockedReason,
 } from "./ListingCard.js";
+export { ListingSerpCard } from "./ListingSerpCard.js";
+export type {
+  ListingSerpCardProps,
+  ListingSerpCardBaseProps,
+  ListingPriceTrend,
+} from "./ListingSerpCard.js";
+export { ListingFeedCard } from "./ListingFeedCard.js";
+export type {
+  ListingFeedCardProps,
+  ListingFeedCardBaseProps,
+} from "./ListingFeedCard.js";
+export { FeedGrid, FEED_GRID_COLUMNS } from "./FeedGrid.js";
+export type { FeedGridProps } from "./FeedGrid.js";
 export { ListingDetailPane, DETAIL_MEASURE, DETAIL_PHOTO_MIN } from "./ListingDetailPane.js";
 export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
 export { ListingComposerPage, COMPOSER_MEASURE } from "./ListingComposerPage.js";

package/src/i18n/es.ts

@@ -76,6 +76,10 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.card.favorite_remove": "Quitar de favoritos",
   "listings.card.untitled": "Anuncio sin título",
   "listings.card.sign_in": "Iniciar sesión",
+  "listings.card.photos": "Fotos de este anuncio",
+  "listings.card.price_was": "Antes",
+  "listings.card.price_dropped": "El precio ha bajado",
+  "listings.card.price_raised": "El precio ha subido",
 
   "listings.detail.loading": "Cargando el anuncio…",
   "listings.detail.load_failed": "No pudimos cargar este anuncio",

package/src/i18n/keys.ts

@@ -75,6 +75,17 @@ export const LISTINGS_I18N_KEYS = {
   cardUntitled: "listings.card.untitled",
   /** The door beside a blocked favourite: the container supplies WHERE. */
   cardSignIn: "listings.card.sign_in",
+  /** The accessible name of `<ListingSerpCard>`'s photo strip. `SkinCarousel`
+   * requires one — an unnamed scrollable region is announced as nothing — and
+   * the token bridge owns no i18n engine, so the copy is this pair's. */
+  cardPhotos: "listings.card.photos",
+  /** The label on the struck-through previous price. The strike is styling and
+   * a screen reader announces none of it, so the word is on the line. */
+  cardPriceWas: "listings.card.price_was",
+  /** The name of the trend arrow — the whole message of a glyph that would
+   * otherwise be a decoration nobody can read. */
+  cardPriceDropped: "listings.card.price_dropped",
+  cardPriceRaised: "listings.card.price_raised",
 
   // ── detail ───────────────────────────────────────────────────────────────
   detailLoading: "listings.detail.loading",
@@ -258,6 +269,10 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.card.favorite_remove": "Remove from favourites",
   "listings.card.untitled": "Untitled listing",
   "listings.card.sign_in": "Sign in",
+  "listings.card.photos": "Photos of this listing",
+  "listings.card.price_was": "Was",
+  "listings.card.price_dropped": "The price went down",
+  "listings.card.price_raised": "The price went up",
 
   "listings.detail.loading": "Loading the listing…",
   "listings.detail.load_failed": "We could not load this listing",

package/src/i18n/ru.ts

@@ -92,6 +92,10 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.card.favorite_remove": "Убрать из избранного",
   "listings.card.untitled": "Объявление без названия",
   "listings.card.sign_in": "Войти",
+  "listings.card.photos": "Фотографии объявления",
+  "listings.card.price_was": "Было",
+  "listings.card.price_dropped": "Цена снизилась",
+  "listings.card.price_raised": "Цена выросла",
 
   "listings.detail.loading": "Загружаем объявление…",
   "listings.detail.load_failed": "Не удалось загрузить объявление",