@stapel/listings-react 0.4.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/listings-react",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Headless React pair for stapel-listings: a typed client over the draft twin, the composer that turns a category schema into a submittable listing, and the owner's dashboard. Two independent axes are rendered as two — lifecycle `status` decides visibility and `moderation_status` decides nothing about it, so an edit to a live listing stays live and says 'under review' instead of vanishing. Feature values are drawn and mirrored by @stapel/attributes-react; photos arrive as an injected upload bag whose `refs` ARE `images_draft` and whose `settled` gates the submit; a publish refusal is routed onto the control that caused it by slug. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
   "license": "MIT",
   "repository": {
@@ -53,14 +53,14 @@
       "limit": "11 KB"
     },
     {
-      "name": "default — the antd skin (card, detail, composer, dashboard) must stay out of the main bundle",
+      "name": "default — the antd skin (card, detail, composer, dashboard, the four named slots and the delete confirmation) must stay out of the main bundle",
       "path": "dist/default/index.js",
-      "limit": "14 KB"
+      "limit": "16 KB"
     },
     {
       "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
       "path": "dist/i18n/ru.js",
-      "limit": "4.5 KB"
+      "limit": "5 KB"
     },
     {
       "name": "i18n/es — the Spanish bundle is opt-in, not carried by the main entry",
@@ -70,14 +70,18 @@
   ],
   "peerDependencies": {
     "@stapel/attributes-react": ">=0.1.0",
-    "@stapel/core": ">=0.16.0 <1.0.0",
+    "@stapel/core": ">=0.18.1 <1.0.0",
+    "@stapel/currencies-react": ">=0.2.0",
     "@stapel/image": ">=0.2.0",
-    "@stapel/tokens-antd": ">=0.5.0",
+    "@stapel/tokens-antd": ">=0.7.0",
     "@tanstack/react-query": "^5.0.0",
     "antd": ">=5.20.0 <7",
     "react": ">=19"
   },
   "peerDependenciesMeta": {
+    "@stapel/currencies-react": {
+      "optional": true
+    },
     "@stapel/tokens-antd": {
       "optional": true
     },
@@ -98,12 +102,13 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.2.0",
-    "@stapel/core": "^0.17.0",
-    "@stapel/image": "^0.3.0",
-    "@stapel/showcase": "^0.2.0",
-    "@stapel/tokens": "^0.5.0",
-    "@stapel/tokens-antd": "^0.5.0"
+    "@stapel/attributes-react": "^0.3.1",
+    "@stapel/core": "^0.18.1",
+    "@stapel/currencies-react": "^0.2.0",
+    "@stapel/image": "^0.4.1",
+    "@stapel/showcase": "^0.3.0",
+    "@stapel/tokens": "^0.5.1",
+    "@stapel/tokens-antd": "^0.7.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/listings-react",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -664,7 +664,7 @@ export interface components {
             images_draft?: string[];
             location_id_draft?: string;
             location_label_draft?: string;
-            geohash_draft?: string;
+            readonly geohash_draft: string;
             /** Format: decimal */
             lat_draft?: string | null;
             /** Format: decimal */
@@ -805,7 +805,7 @@ export interface components {
             images_draft?: string[];
             location_id_draft?: string;
             location_label_draft?: string;
-            geohash_draft?: string;
+            readonly geohash_draft?: string;
             /** Format: decimal */
             lat_draft?: string | null;
             /** Format: decimal */

package/src/default/FavoritesPane.tsx

@@ -6,19 +6,53 @@
  * "You have not saved anything yet" and "we could not load your favourites"
  * are the pair a `data ?? []` would have merged, and merging them is exactly
  * the substitution that cost the fleet an incident (spec §7.4).
+ *
+ * ── A visitor is told ONE thing ────────────────────────────────────────────
+ *
+ * `useFavorites` disables the query without a mandate, so a visitor's `rows`
+ * sit in `loading` forever — and the pane rendered the blocked notice AND the
+ * spinner underneath it, saying "you cannot see this" and "we are fetching it"
+ * at the same time, with no sign-in link anywhere on the screen. The gate is
+ * now the WHOLE body: one designed state, with the door the container supplies
+ * (`signIn`) inside it, and nothing else drawn.
+ *
+ * The pager obeys the same rule. `Previous`/`Next` were rendered disabled in
+ * every state including empty, failed and blocked — two controls that meant
+ * nothing, three times over. They render when there is a page to go to.
+ *
+ * And each one renders only when ITS page exists. The keyset gates name the
+ * missing page with the button's own label key, so a blocked `Previous` drew
+ * the word twice — once as a dead button, once as its own "reason". A pager
+ * does not explain itself: the page indicator says where you are, and a
+ * direction with nowhere to go is simply not drawn.
  */
-import type { ReactElement } from "react";
-import { Alert, Button, Empty, Flex, Space, Spin, Typography } from "antd";
-import { matchList, useDescribeFlowError, useT } from "@stapel/core";
-import type { LinkComponent } from "@stapel/core";
+import type { ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import {
+  EmptyState,
+  ErrorAlert,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
+import { matchList, useT } from "@stapel/core";
+import type { LinkComponent, SignInCtaProp } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
 import { useFavorites } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import { ErrorAlert } from "./ErrorAlert.js";
 import { ListingCard } from "./ListingCard.js";
 import type { ListingCardOpenProps } from "./ListingCard.js";
-import { ListingsSkinTheme } from "./theme.js";
+import { SignInLink } from "./SignInLink.js";
 import type { ThemeModeProp } from "./types.js";
 
+/** The narrowest a card may get before the grid drops a column — the same
+ * element-relative rule the detail gallery uses. It was `width: 240`, which
+ * left two cards floating in a 2560px pane and overflowed a 390px one. */
+export const FAVORITES_CARD_MIN = "15rem";
+
+/** How wide the saved grid may get before it stops being a grid and becomes
+ * three cards adrift in a 1280px window. A measure, not a breakpoint: the
+ * cards keep filling it, and past it the page centres. */
+export const FAVORITES_MEASURE = "72rem";
+
 /** How a card in this grid opens — the same one-contract union `<ListingCard>`
  * takes, one level up, so a pane cannot re-introduce the double navigation the
  * card no longer allows. */
@@ -41,7 +75,21 @@ export type FavoritesPaneOpenProps =
       readonly linkComponent?: undefined;
     };
 
-export type FavoritesPaneProps = ThemeModeProp & FavoritesPaneOpenProps;
+/** The way OUT of an empty favourites list. */
+export interface FavoritesBrowseCtaProp {
+  /**
+   * What a person with nothing saved can do next — a "Browse listings"
+   * button, supplied by the container because only it knows where the
+   * catalogue lives. An empty state without one is a dead end, and this
+   * screen was one of four sharing a single stock illustration and no exit.
+   */
+  readonly browseCta?: ReactNode;
+}
+
+export type FavoritesPaneProps = ThemeModeProp &
+  SignInCtaProp &
+  FavoritesBrowseCtaProp &
+  FavoritesPaneOpenProps;
 
 /** The card's own open props for one row. One arm, never two. */
 function cardOpenProps(
@@ -60,93 +108,119 @@ function cardOpenProps(
 
 export function FavoritesPane(props: FavoritesPaneProps): ReactElement {
   const t = useT();
-  const describe = useDescribeFlowError();
   const bag = useFavorites();
+  const paged = bag.prevPage.available || bag.nextPage.available;
 
   return (
-    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
-      <Flex vertical gap={16} data-testid="listings-favorites">
+    <SkinTheme
+      surface="base"
+      style={{ padding: spacing[4], maxWidth: FAVORITES_MEASURE }}
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <Flex vertical gap={spacing[4]} data-testid="listings-favorites">
         <Typography.Title level={3}>
           {t(LISTINGS_I18N_KEYS.favoritesTitle)}
         </Typography.Title>
 
         {!bag.gate.available ? (
-          <Alert
-            type="info"
-            showIcon
-            data-testid="listings-favorites-blocked"
-            message={t(bag.gate.block.code, bag.gate.block.params)}
+          // The whole body, not a banner over a spinner. A blocked screen has
+          // one state and it carries its own way out.
+          <EmptyState
+            testId="listings-favorites-blocked"
+            title={t(bag.gate.block.code, bag.gate.block.params)}
+            hint={t(LISTINGS_I18N_KEYS.favoritesSignInHint)}
+            action={
+              <SignInLink cta={props.signIn} testId="listings-favorites-sign-in" />
+            }
           />
-        ) : null}
-
-        {matchList(bag.rows, {
-          loading: () => (
-            <Flex justify="center" data-testid="listings-favorites-loading">
-              <Spin aria-label={t(LISTINGS_I18N_KEYS.favoritesLoading)} />
-            </Flex>
-          ),
-          failed: () => (
-            <ErrorAlert
-              testId="listings-favorites-error"
-              error={describe({
-                code: LISTINGS_I18N_KEYS.favoritesLoadFailed,
-                params: {},
-                status: 0,
-                message: undefined,
-                language: undefined,
-              })}
-              action={
-                <Button
-                  size="small"
-                  data-analytics="none"
-                  data-analytics-reason="retrying a read the person already asked for; not a business action"
-                  onClick={bag.refetch}
+        ) : (
+          <>
+            {matchList(bag.rows, {
+              loading: () => (
+                <div
+                  role="status"
+                  aria-busy="true"
+                  aria-label={t(LISTINGS_I18N_KEYS.favoritesLoading)}
+                  data-testid="listings-favorites-loading"
+                  data-stapel-load-state="loading"
+                />
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="listings-favorites-error"
+                  thrown={error}
+                  message={t(LISTINGS_I18N_KEYS.favoritesLoadFailed)}
+                  onRetry={bag.refetch}
+                  retryLabel={t(LISTINGS_I18N_KEYS.mineRetry)}
+                />
+              ),
+              empty: () => (
+                <EmptyState
+                  testId="listings-favorites-empty"
+                  title={t(LISTINGS_I18N_KEYS.favoritesEmpty)}
+                  hint={t(LISTINGS_I18N_KEYS.favoritesEmptyHint)}
+                  {...(props.browseCta !== undefined
+                    ? { action: props.browseCta }
+                    : {})}
+                />
+              ),
+              ready: (rows) => (
+                <div
+                  data-testid="listings-favorites-grid"
+                  style={{
+                    display: "grid",
+                    gridTemplateColumns: `repeat(auto-fill, minmax(${FAVORITES_CARD_MIN}, 1fr))`,
+                    gap: spacing[4],
+                  }}
                 >
-                  {t(LISTINGS_I18N_KEYS.mineRetry)}
-                </Button>
-              }
-            />
-          ),
-          empty: () => (
-            <Empty
-              data-testid="listings-favorites-empty"
-              description={t(LISTINGS_I18N_KEYS.favoritesEmpty)}
-            />
-          ),
-          ready: (rows) => (
-            <Flex wrap gap={16} data-testid="listings-favorites-grid">
-              {rows.map((row) => (
-                <div key={row.id} style={{ width: 240 }}>
-                  <ListingCard listing={row} {...cardOpenProps(props, row.id)} />
+                  {rows.map((row) => (
+                    <ListingCard
+                      key={row.id}
+                      listing={row}
+                      blockedReason="line"
+                      {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
+                      {...cardOpenProps(props, row.id)}
+                    />
+                  ))}
                 </div>
-              ))}
-            </Flex>
-          ),
-        })}
+              ),
+            })}
 
-        <Space>
-          <Button
-            size="small"
-            disabled={!bag.prevPage.available}
-            data-testid="listings-favorites-prev"
-            data-analytics="none"
-            data-analytics-reason="paging a list the person is already reading; not a business action"
-            onClick={bag.goPrev}
-          >
-            {t(LISTINGS_I18N_KEYS.pagePrev)}
-          </Button>
-          <Button
-            size="small"
-            disabled={!bag.nextPage.available}
-            data-testid="listings-favorites-next"
-            data-analytics="none"
-            data-analytics-reason="paging a list the person is already reading; not a business action"
-            onClick={bag.goNext}
-          >
-            {t(LISTINGS_I18N_KEYS.pageNext)}
-          </Button>
-        </Space>
+            {paged ? (
+              <Flex gap={spacing[3]} wrap align="center">
+                {bag.prevPage.available ? (
+                  <Button
+                    size="small"
+                    data-testid="listings-favorites-prev"
+                    data-analytics="none"
+                    data-analytics-reason="paging a list the person is already reading; not a business action"
+                    onClick={bag.goPrev}
+                  >
+                    {t(LISTINGS_I18N_KEYS.pagePrev)}
+                  </Button>
+                ) : null}
+                <Typography.Text
+                  type="secondary"
+                  data-testid="listings-favorites-page"
+                >
+                  {t(LISTINGS_I18N_KEYS.pageIndicator, { page: bag.pageNumber })}
+                </Typography.Text>
+                {bag.nextPage.available ? (
+                  <Button
+                    size="small"
+                    data-testid="listings-favorites-next"
+                    data-analytics="none"
+                    data-analytics-reason="paging a list the person is already reading; not a business action"
+                    onClick={bag.goNext}
+                  >
+                    {t(LISTINGS_I18N_KEYS.pageNext)}
+                  </Button>
+                ) : null}
+              </Flex>
+            ) : null}
+          </>
+        )}
       </Flex>
-    </ListingsSkinTheme>
+    </SkinTheme>
   );
 }

package/src/default/ListingCard.tsx

@@ -22,19 +22,24 @@
  * card. That property is the whole reason the projection exists, and it is
  * what makes a grid of forty cards cost one query.
  *
- * ── The heart is never hidden ──────────────────────────────────────────────
+ * ── The heart is never hidden, and never explained by hover ────────────────
  *
  * A visitor sees it, blocked, with the reason IN WORDS beside it and the
  * sign-in link the container supplies (`signIn`, typically `?next=<current>`).
  * Hiding it would teach nobody that favourites exist (private-space canon
- * §6.3, spec §6.2 item 6) — and until 0.3.0 the reason lived only in a tooltip
- * on a disabled button, which receives no pointer events in any browser: a
- * reason nobody could read, and no door to walk through.
+ * §6.3, spec §6.2 item 6). The reason itself goes through the shared
+ * `<GatedControl>`, which renders it as text linked by `aria-describedby` —
+ * a disabled antd button receives no pointer events and is not focusable, so
+ * the `Tooltip` this component used to offer as a "quieter" volume was a
+ * reason nobody could read on any device. That arm is gone; `blockedReason`
+ * is now "text" (reason + door) or "line" (reason alone, for a grid).
  */
 import type { ReactElement, ReactNode } from "react";
-import { Button, Card, Flex, Tooltip, Typography } from "antd";
+import { Button, Card, Flex, Typography } from "antd";
+import { GatedControl, SkinTheme } from "@stapel/tokens-antd/skin";
 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";
@@ -44,7 +49,7 @@ import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { HeartIcon } from "./icons.js";
 import { SignInLink } from "./SignInLink.js";
 import { ListingPhoto } from "./ListingPhoto.js";
-import { ListingsSkinTheme } from "./theme.js";
+import { ListingPrice } from "./ListingPrice.js";
 import type { ThemeModeProp } from "./types.js";
 
 /**
@@ -87,8 +92,27 @@ export type ListingCardOpenProps =
       readonly linkComponent?: undefined;
     };
 
+/**
+ * How loudly a blocked favourite states its reason on THIS surface.
+ *
+ * `"text"` (the default) is the sentence under the controls, with the sign-in
+ * door beside it — the right volume for a card that stands alone.
+ *
+ * `"line"` collapses it to the reason alone, no door: a grid of forty cards
+ * repeating "sign in to do this — sign in" forty times is not forty pieces of
+ * help, it is the loudest thing on the page, and every one of those doors
+ * leads where the header's own sign-in button already leads.
+ *
+ * There is no third setting. The reason is on screen in both, because the only
+ * way to make it quieter than a line of text is to hide it behind hover, and
+ * hover does not exist on the device most of these cards are read on.
+ */
+export type ListingCardBlockedReason = "text" | "line";
+
 export interface ListingCardBaseProps extends ThemeModeProp, SignInCtaProp {
   readonly listing: ListingCardData;
+  /** See {@link ListingCardBlockedReason}. Default `"text"`. */
+  readonly blockedReason?: ListingCardBlockedReason;
   /** Extra chrome the container adds (a `promoted` tag from search, say —
    * DSA Art. 26 marking belongs to the pair that receives it). */
   readonly badge?: ReactNode;
@@ -105,6 +129,11 @@ export type ListingCardProps = ListingCardBaseProps & ListingCardOpenProps;
  * Exactly one of the three renders, so exactly one navigation happens per
  * click. That is the whole fix — the branch below has no arm in which both a
  * handler and an `href` reach the DOM.
+ *
+ * It is the card's PRIMARY action and is drawn as one: a full-width button,
+ * which on a phone is 44px tall because `SkinTheme` sets antd's
+ * `controlHeight` there. It was a bare text link beside a 40px icon button,
+ * with no hierarchy between them and neither one a real touch target.
  */
 function OpenControl(
   props: ListingCardOpenProps & { readonly listingId: number }
@@ -131,8 +160,8 @@ function OpenControl(
       </Link>
     ) : (
       <Button
-        size="small"
-        type="link"
+        type="primary"
+        block
         href={props.href}
         data-testid="listings-card-open"
         data-analytics="none"
@@ -147,8 +176,8 @@ function OpenControl(
     const onOpen = props.onOpen;
     return (
       <Button
-        size="small"
-        type="link"
+        type="primary"
+        block
         data-testid="listings-card-open"
         data-analytics="none"
         data-analytics-reason="business action — host app wraps with its own tracked()"
@@ -175,12 +204,9 @@ export function ListingCard(props: ListingCardProps): ReactElement {
   const titleDaos = asFeatureDaoList(listing.features_title);
 
   const status = listing.status === undefined ? undefined : lifecycleCaption(listing.status);
-  const price =
-    listing.price !== undefined && listing.price.length > 0
-      ? `${listing.price} ${listing.currency ?? ""}`.trim()
-      : t(LISTINGS_I18N_KEYS.cardPriceAbsent);
 
   const favoriteGate = useActionGate(favorite.gate);
+  const blockedReason = props.blockedReason ?? "text";
 
   const favoriteLabel = t(
     favorite.favorited
@@ -189,7 +215,10 @@ export function ListingCard(props: ListingCardProps): ReactElement {
   );
 
   return (
-    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+    <SkinTheme
+      surface="bare"
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
       <Card
         size="small"
         data-testid="listings-card"
@@ -197,19 +226,22 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        styles={{ body: { minWidth: 0 } }}
         cover={
           <ListingPhoto
             imageRef={listing.images?.[0]}
             alt={listing.title ?? String(listing.id)}
-            style={{ aspectRatio: "4 / 3" }}
           />
         }
       >
-        <Flex vertical gap={4}>
+        <Flex vertical gap={spacing[1]} style={{ minWidth: 0 }}>
           {props.badge}
 
           <Typography.Text strong data-testid="listings-card-price">
-            {price}
+            <ListingPrice
+              amount={listing.price}
+              {...(listing.currency !== undefined ? { currency: listing.currency } : {})}
+            />
           </Typography.Text>
 
           <Typography.Text ellipsis data-testid="listings-card-title">
@@ -242,24 +274,32 @@ export function ListingCard(props: ListingCardProps): ReactElement {
             </Typography.Text>
           ) : null}
 
-          <Flex gap={8} align="center">
+          {/* The action row is wrapped in ONE `GatedControl`, so the reason a
+              blocked heart carries lands full width UNDER both controls
+              rather than in the two-centimetre column beside the icon. */}
+          {props.showFavorite === false ? (
             <OpenControl {...props} listingId={listing.id} />
-
-            {props.showFavorite === false ? null : (
-              <Tooltip
-                title={
-                  favorite.gate.available
-                    ? favoriteLabel
-                    : t(favorite.gate.block.code, favorite.gate.block.params)
-                }
-              >
-                {/* A disabled antd Button swallows pointer events, so the
-                    tooltip needs the wrapper to hear them — which is also
-                    what makes the REASON reachable by keyboard. */}
-                <span data-testid="listings-card-favorite-wrap">
+          ) : (
+            <GatedControl
+              gate={favorite.gate}
+              testId="listings-card-actions"
+              style={{ width: "100%" }}
+            >
+              {(bind) => (
+                <Flex
+                  gap={spacing[2]}
+                  align="center"
+                  style={{ width: "100%", minWidth: 0 }}
+                >
+                  <div style={{ flex: "1 1 auto", minWidth: 0 }}>
+                    <OpenControl {...props} listingId={listing.id} />
+                  </div>
                   <Button
-                    size="small"
-                    disabled={!favorite.gate.available}
+                    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={favoriteLabel}
                     aria-pressed={favorite.favorited}
                     data-testid="listings-card-favorite"
@@ -269,27 +309,29 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                     onClick={favorite.toggle}
                     icon={<HeartIcon filled={favorite.favorited} />}
                   />
-                </span>
-              </Tooltip>
-            )}
-          </Flex>
+                </Flex>
+              )}
+            </GatedControl>
+          )}
 
-          {/* The reason IN WORDS, plus the door. A tooltip on a disabled
-              button is a reason nobody can read (core's actionGate.ts says so
-              in as many words), and a reason with no next action leaves the
-              visitor hunting for the header — which is what the storefront
-              had to write a paragraph about instead of shipping the screen. */}
-          {props.showFavorite === false || favoriteGate.reason === undefined ? null : (
+          {/* The door. `GatedControl` above already prints the reason and
+              wires `aria-describedby` to it; what it cannot know is WHERE a
+              visitor signs in, which is the container's business and arrives
+              as `signIn`. On a grid `blockedReason="line"` drops the door and
+              keeps the sentence — twenty-four doors to one place is not
+              twenty-four pieces of help. */}
+          {props.showFavorite === false ||
+          favoriteGate.reason === undefined ||
+          blockedReason === "line" ? null : (
             <Typography.Text
               type="secondary"
               data-testid="listings-card-favorite-blocked"
             >
-              {favoriteGate.reason}
               <SignInLink cta={props.signIn} testId="listings-card-sign-in" />
             </Typography.Text>
           )}
         </Flex>
       </Card>
-    </ListingsSkinTheme>
+    </SkinTheme>
   );
 }