@stapel/listings-react 0.21.0 → 0.22.0

package/src/api/generated/schema.ts

@@ -260,6 +260,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/listings/api/v1/listings/{id}/transition/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Move the listing to ``to``, if that is a move its OWNER may make.
+         *
+         *     The seller's way forward, as one route instead of one endpoint per
+         *     edge. ``archive`` and ``complete`` were the only two the API ever
+         *     offered, and both of them are exits — so a listing that reached
+         *     ARCHIVED, PAUSED, EXPIRED, SOLD, REJECTED or BLOCKED had no call left
+         *     that would move it, and the cabinet correctly showed its owner
+         *     nothing but «удалить».
+         *
+         *     Which moves exist is ``models.OWNER_TRANSITIONS``, and it is the same
+         *     list ``available_transitions`` puts on the card — the point of routing
+         *     every edge through one allowlist is that the set a client is offered
+         *     and the set the server accepts are one object, not two that agree
+         *     today.
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["listings_api_v1_listings_transition_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/listings/api/v1/listings/{id}/unfavorite/": {
         parameters: {
             query?: never;
@@ -437,6 +471,8 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /** @enum {string} */
+        AvailableTransitionsEnum: "draft" | "pending" | "published" | "paused" | "expired" | "sold" | "rejected" | "blocked" | "archived";
         /** @description Serializer for boolean feature DAO. */
         BoolDao: {
             name?: string | null;
@@ -815,6 +851,11 @@ export interface components {
             lat?: string | null;
             /** Format: decimal */
             lon?: string | null;
+            /**
+             * Format: double
+             * @description How wide the area `lat`/`lon` describe, in kilometres. On a PUBLIC read this is ~1.113 (the pair is rounded to two decimals and `geohash` comes back empty): draw a CIRCLE, never a marker — the listing is somewhere in it, and for a private seller the true point is a home address. `0` means the exact point, which only the listing's own owner, staff and the service transport get. Proximity itself is unaffected: `distance_km` on a search hit is computed server-side from the true coordinates.
+             */
+            readonly geo_precision_km: number;
             countable?: boolean;
             /** Format: int64 */
             stock_quantity?: number | null;
@@ -845,6 +886,11 @@ export interface components {
             lat?: string | null;
             /** Format: decimal */
             lon?: string | null;
+            /**
+             * Format: double
+             * @description How wide the area `lat`/`lon` describe, in kilometres. On a PUBLIC read this is ~1.113 (the pair is rounded to two decimals and `geohash` comes back empty): draw a CIRCLE, never a marker — the listing is somewhere in it, and for a private seller the true point is a home address. `0` means the exact point, which only the listing's own owner, staff and the service transport get. Proximity itself is unaffected: `distance_km` on a search hit is computed server-side from the true coordinates.
+             */
+            readonly geo_precision_km: number;
             readonly features: (components["schemas"]["FeatureDao"] | {
                 slug?: string;
                 type?: string;
@@ -981,13 +1027,29 @@ export interface components {
             owner_id: string;
         };
         /**
-         * @description * `pending` - Pending Review
+         * @description The body of ``POST listings/{id}/transition/``: where to move it.
+         *
+         *     A ``ChoiceField`` over the whole lifecycle rather than over the moves this
+         *     particular listing has, because the two refusals are different sentences
+         *     and a client should be able to tell them apart: a status that does not
+         *     exist is a 400 (the caller is confused about the vocabulary), a status
+         *     that exists but is not this listing's to reach is a 409 with
+         *     ``from_status`` (the caller is confused about the row). Narrowing the
+         *     field to the per-row set would collapse both into 400 and lose the
+         *     ``from_status`` that tells a storefront what to re-render.
+         */
+        ListingTransitionRequest: {
+            to: components["schemas"]["ToEnum"];
+        };
+        /**
+         * @description * `not_submitted` - Not submitted for review
+         *     * `pending` - Pending Review
          *     * `approved` - Approved
          *     * `rejected` - Rejected
          *     * `needs_review` - Needs Manual Review
          * @enum {string}
          */
-        ModerationStatusEnum: "pending" | "approved" | "rejected" | "needs_review";
+        ModerationStatusEnum: "not_submitted" | "pending" | "approved" | "rejected" | "needs_review";
         /** @description Listing counts by tab for the current user. */
         MyCountersResponse: {
             active: number;
@@ -1059,6 +1121,11 @@ export interface components {
             lat?: string | null;
             /** Format: decimal */
             lon?: string | null;
+            /**
+             * Format: double
+             * @description How wide the area `lat`/`lon` describe, in kilometres. On a PUBLIC read this is ~1.113 (the pair is rounded to two decimals and `geohash` comes back empty): draw a CIRCLE, never a marker — the listing is somewhere in it, and for a private seller the true point is a home address. `0` means the exact point, which only the listing's own owner, staff and the service transport get. Proximity itself is unaffected: `distance_km` on a search hit is computed server-side from the true coordinates.
+             */
+            readonly geo_precision_km: number;
             countable?: boolean;
             /** Format: int64 */
             stock_quantity?: number | null;
@@ -1067,6 +1134,7 @@ export interface components {
             readonly viewed: boolean | null;
             readonly view_count: number;
             moderation_status?: components["schemas"]["ModerationStatusEnum"];
+            readonly available_transitions: components["schemas"]["AvailableTransitionsEnum"][];
             title_draft?: string;
             /** Format: decimal */
             price_draft?: string | null;
@@ -1286,6 +1354,19 @@ export interface components {
          * @enum {string}
          */
         StyleEnum: "l" | "m";
+        /**
+         * @description * `draft` - Draft
+         *     * `pending` - Pending Moderation
+         *     * `published` - Published
+         *     * `paused` - Paused
+         *     * `expired` - Expired
+         *     * `sold` - Sold
+         *     * `rejected` - Rejected
+         *     * `blocked` - Blocked (moderation takedown)
+         *     * `archived` - Archived
+         * @enum {string}
+         */
+        ToEnum: "draft" | "pending" | "published" | "paused" | "expired" | "sold" | "rejected" | "blocked" | "archived";
         /**
          * @description * `convertible_unit` - convertible_unit
          * @enum {string}
@@ -1663,6 +1744,48 @@ export interface operations {
             };
         };
     };
+    listings_api_v1_listings_transition_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description A unique integer value identifying this listing. */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ListingTransitionRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["ListingTransitionRequest"];
+                "multipart/form-data": components["schemas"]["ListingTransitionRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ListingActionResponse"];
+                };
+            };
+            /** @description No response body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No response body */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listings_api_v1_listings_unfavorite_create: {
         parameters: {
             query?: never;

package/src/api/listingsApi.ts

@@ -7,6 +7,7 @@ import type {
   ListingEngagementBatch,
   ListingDraft,
   ListingDraftPatch,
+  ListingOwnerTransition,
   ListingPageParams,
   ListingStatusInfo,
   MyCounters,
@@ -204,6 +205,29 @@ export interface ListingsApi {
   /** Mark SOLD. Same 409 contract as {@link archive}. */
   complete(id: number): Promise<ListingActionResponse>;
 
+  /**
+   * Move the listing to `to` — ONE route for every edge a seller owns
+   * (`POST listings/{id}/transition/`, stapel-listings 0.20.0).
+   *
+   * {@link archive} and {@link complete} are still here and still work; they
+   * are two named exits, and for two releases they were the ONLY two the
+   * owner API had. That is what made a cabinet a one-way door: every status a
+   * seller could put a listing INTO — SOLD, ARCHIVED, PAUSED, EXPIRED — was
+   * one no call could get it out of, and `DELETE` was the only answer left.
+   *
+   * The set this accepts is `models.OWNER_TRANSITIONS`, which is the same set
+   * `MyListingCard.available_transitions` reports, deliberately: the moves a
+   * client is offered and the moves the server takes are one object rather
+   * than two that agree today. Two refusals, and they are different
+   * sentences — a status that does not exist is a 400, a status that exists
+   * but is not this row's to reach is `error.409.invalid_listing_transition`
+   * with `params.from_status`.
+   */
+  transition(
+    id: number,
+    to: ListingOwnerTransition
+  ): Promise<ListingActionResponse>;
+
   /** Favourite a listing. Idempotent server-side (`get_or_create`). */
   favorite(id: number): Promise<FavoriteToggleResponse>;
 
@@ -306,6 +330,9 @@ export function createListingsApi(client: StapelClient): ListingsApi {
 
     complete: (id) => client.post(`${listingPath(id)}complete/`),
 
+    transition: (id, to) =>
+      client.post(`${listingPath(id)}transition/`, { to }),
+
     favorite: (id) => client.post(`${listingPath(id)}favorite/`),
 
     unfavorite: (id) => client.post(`${listingPath(id)}unfavorite/`),

package/src/api/types.ts

@@ -140,8 +140,27 @@ export type ListingDetail = WithOptionalEngagement<Schemas["ListingDetail"]>;
  * type, for data no one can supply; it is precisely the case
  * `<ListingEngagementScope>` exists to answer. A deployment running a server
  * older than 0.16 is the same shape of fact.
+ *
+ * `geo_precision_km` is relaxed for the same reason and by the same argument.
+ * stapel-listings 0.21.0 puts it on every card this module serves — how wide
+ * an area `lat`/`lon` describe, so a reader draws a circle instead of pinning
+ * a private seller's front door with a marker — and the SEARCH document does
+ * not carry it, because stapel-search coarsens its own card independently
+ * (`CARD_COORD_PRECISION`, the same ~1.1km). Requiring it on the prop would
+ * make the pair's primary consumer unable to satisfy its own type for a
+ * number nobody in that path holds. A reader that needs the precision must
+ * treat its absence as UNSTATED and never as `0`: `0` means the exact point,
+ * which is the one reading that could publish an address.
  */
-export type ListingCard = WithOptionalEngagement<Schemas["ListingCard"]>;
+type WithOptionalPrecision<Row extends { geo_precision_km?: number }> = Omit<
+  Row,
+  "geo_precision_km"
+> &
+  Partial<Pick<Schemas["ListingCard"], "geo_precision_km">>;
+
+export type ListingCard = WithOptionalPrecision<
+  WithOptionalEngagement<Schemas["ListingCard"]>
+>;
 
 /** `POST /listings/` request+response and `POST /{pk}/save-draft/` response —
  * the draft twin. Every user-editable field is a `*_draft` one, promoted onto
@@ -197,7 +216,9 @@ 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 = WithOptionalEngagement<Schemas["MyListingCard"]>;
+export type MyListingCard = WithOptionalPrecision<
+  WithOptionalEngagement<Schemas["MyListingCard"]>
+>;
 
 /** The keyset envelope `GET /listings/my/listings/` comes back in — the same
  * `IDAnchorPagination` shape as {@link PaginatedListingCards}, over the owner
@@ -232,9 +253,33 @@ export const LISTING_STATUSES: readonly ListingLifecycleStatus[] = [
  * only one (`models.py`: "no visibility-reads-moderation_status coupling"). */
 export type ListingLifecycleStatus = Schemas["StatusD41Enum"];
 
+/**
+ * One move the OWNER of a listing may make from where it is now — the third
+ * axis, and the one stapel-listings 0.20.0 added because the first two cannot
+ * answer it.
+ *
+ * `status` says where the listing IS and `moderation_status` says what is
+ * being waited on. Neither says *what can I do about it*, and a dashboard
+ * that works it out for itself is re-implementing `models.OWNER_TRANSITIONS`
+ * from the outside — which is how a cabinet ends up drawing "Mark sold" on a
+ * listing that is already sold, and drawing no way back at all.
+ *
+ * The values are lifecycle states (the DESTINATION of a move), so this is
+ * `ListingLifecycleStatus` narrowed by the server rather than a second
+ * vocabulary.
+ */
+export type ListingOwnerTransition = Schemas["AvailableTransitionsEnum"];
+
 /** The four content-moderation states, as `models.ModerationStatus` declares
  * them. Independent of the lifecycle: see `model/status.ts`. */
 export const MODERATION_STATUSES: readonly ListingModerationStatus[] = [
+  // NOBODY HAS ASKED YET, and it is the DEFAULT (stapel-listings 0.20.0).
+  // Before it, a draft was born `pending` and every dashboard row announced a
+  // moderation decision that no case existed behind — one live stand held 167
+  // of them. The distinction lives in the data because every reader asks the
+  // same question and would each otherwise re-derive "…unless it was never
+  // submitted" from a second column.
+  "not_submitted",
   "pending",
   "approved",
   "rejected",

package/src/default/ListingCard.tsx

@@ -107,7 +107,12 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Card, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
-import { ErrorAlert, GatedControl, SkinTheme } from "@stapel/tokens-antd/skin";
+import {
+  ErrorAlert,
+  GatedControl,
+  SKIN_CAROUSEL_SLIDE_CLASS,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
 import { useActionGate, useT } from "@stapel/core";
 import type { LinkComponent, SignInCtaProp } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
@@ -305,11 +310,37 @@ export function cardTargetCss(): string {
   return [
     `.${CARD_TARGET_CLASS}{display:block;color:inherit;text-decoration:none}`,
     `.${CARD_TARGET_CLASS}:focus-visible{outline:2px solid var(--listing-card-focus);outline-offset:2px}`,
+    // A PRESS, answered where the press lands (D176). The rule is on the
+    // TARGET rather than on the card's frame because that is the one element
+    // all three surfaces share: the feed tile is a bare div with this anchor
+    // over it and no card chrome at all, so a rule written for the frame
+    // reached the two surfaces that have one and missed the phone's home
+    // screen entirely. `matchMedia("(hover: hover)")` is false on that
+    // device, which makes this the ONLY feedback a finger ever gets between
+    // touching a tile and the next screen arriving.
+    `.${CARD_TARGET_CLASS}{transition:transform 90ms ease}`,
+    `.${CARD_TARGET_CLASS}:active{transform:scale(0.985)}`,
+    `@media (prefers-reduced-motion:reduce){.${CARD_TARGET_CLASS}{transition:none}` +
+      `.${CARD_TARGET_CLASS}:active{transform:none;opacity:0.9}}`,
     // The card asks about its OWN width, not the window's — see
     // `LISTING_CARD_ROW_MIN`.
     `${q}{container-type:inline-size}`,
     `${frame}{display:flex;flex-direction:column;min-inline-size:0}`,
-    `${media}{min-inline-size:0}`,
+    // THE MEDIA WELL IS CLIPPED TO THE CARD'S OWN CORNER (D180).
+    //
+    // The photo strip runs edge to edge at the top of a stacked card, so the
+    // card's rounded corner is the corner of the PICTURE. It was not being
+    // cut to it: the well was a square box inside a rounded card, and each
+    // carousel slide carried a radius of its own — so a multi-photo tile drew
+    // a rounded sliver of the next photograph in the corner where the card's
+    // curve should be, and every row of tiles on the live feed read as a set
+    // of pictures with a torn right edge. One radius, stated by the card,
+    // applied to the box that holds the pictures; the slides inside it are
+    // square because the well is what has the shape.
+    `${media}{min-inline-size:0;overflow:hidden;` +
+      `border-start-start-radius:var(--listing-card-radius);` +
+      `border-start-end-radius:var(--listing-card-radius)}`,
+    `${media} .${SKIN_CAROUSEL_SLIDE_CLASS}{border-radius:0}`,
     `${main}{display:flex;flex-direction:column;flex:1 1 auto;min-inline-size:0}`,
     // The row arm. `align-items:flex-start` so a short text column does not
     // stretch the photo, and a fixed media basis so the picture cannot grow
@@ -317,6 +348,9 @@ export function cardTargetCss(): string {
     `@container (min-width:${String(LISTING_CARD_ROW_MIN)}px){` +
       `${frame}{flex-direction:row;align-items:flex-start}` +
       `${media}{flex:0 0 ${String(LISTING_CARD_ROW_MEDIA)}px;` +
+      // Inset on every side in the row arm, so the photo is a rounded block
+      // beside the text rather than two rounded corners and two square ones.
+      `border-radius:var(--listing-card-radius);` +
       `max-inline-size:${String(LISTING_CARD_ROW_MEDIA)}px}` +
       // A full-bleed stacked card has no padding of its own to give the row
       // arm, so the row arm states its own; the reading column's padding is
@@ -333,8 +367,24 @@ export function cardTargetCss(): string {
     // tokens, and a transition that a person who asked for less motion does
     // not get.
     `.${hover}{transition:box-shadow 160ms ease,border-color 160ms ease}`,
-    `.${hover}:hover{box-shadow:var(--listing-card-hover-shadow);` +
-      `border-color:var(--listing-card-focus)}`,
+    // HOVER IS FOR A POINTER THAT HAS ONE. Measured on the phone this loop
+    // walks: `matchMedia("(hover: hover)")` is false, and an unguarded
+    // `:hover` on a touch device is worse than absent — it latches after a
+    // tap and leaves one tile lit until something else is touched.
+    `@media (hover:hover){.${hover}:hover{` +
+      `box-shadow:var(--listing-card-hover-shadow);` +
+      `border-color:var(--listing-card-focus)}}`,
+    // PRESSED, and not the same thing as hovered. The card had a hover state
+    // and nothing at all on the way down, so a tap on a phone — where there
+    // is no hover to begin with — gave no feedback between the finger landing
+    // and the next screen arriving. The lift is TAKEN AWAY rather than
+    // increased: a pressed card is a card pushed into the page, which is the
+    // one direction a shadow can say without a second token.
+    `.${hover}:active{box-shadow:none;border-color:var(--listing-card-focus)}`,
+    // The photo is the largest target on the tile and is its own link, so it
+    // answers a press on its own — the card behind it may not be under the
+    // finger at all.
+    `.${PHOTO_LINK_CLASS}:active{opacity:0.88}`,
     `@media (prefers-reduced-motion:reduce){.${hover}{transition:none}}`,
     // Already seen. The photo and everything inside the card's anchor dim
     // together; the heart is outside the anchor and stays as it was — see
@@ -578,9 +628,23 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         />
       ) : null}
 
+      {/* ONE line, and it truncates (D185). Measured on a live 1440px feed:
+          a two-part city-and-district name wrapped, the text block grew
+          104 -> 128px, and the two cards on either side of it stood 24px
+          shorter — a row of tiles with a ragged bottom edge and a heart
+          hanging below the line it belongs to. The place is a subtitle, not
+          prose: which city it is reads from the first words, and the tile's
+          height must be a property of the GRID rather than of how long this
+          particular neighbourhood is called. The full string stays in the
+          title attribute the way `ellipsis` puts it there, so nothing is
+          lost — it is one hover, or the listing's own page. */}
       {listing.location_label !== undefined &&
       listing.location_label.length > 0 ? (
-        <Typography.Text type="secondary" data-testid="listings-card-location">
+        <Typography.Text
+          type="secondary"
+          ellipsis={{ tooltip: listing.location_label }}
+          data-testid="listings-card-location"
+        >
           {listing.location_label}
         </Typography.Text>
       ) : null}
@@ -617,6 +681,10 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         style={{
           ["--listing-card-focus" as string]: token.colorPrimary,
           ["--listing-card-inset" as string]: `${String(token.paddingSM)}px`,
+          // The card's OWN corner, handed to the media well so the picture is
+          // cut to the same curve the card is drawn with — in whatever theme,
+          // at whatever radius a deployment retuned it to.
+          ["--listing-card-radius" as string]: `${String(token.borderRadiusLG)}px`,
           // The theme's own elevation, so the lift is the same one every
           // raised surface in the skin uses and it is right in both modes.
           ["--listing-card-hover-shadow" as string]: token.boxShadowSecondary,

package/src/default/ListingSerpCard.tsx

@@ -99,6 +99,7 @@ import {
   CARD_MEDIA_CLASS,
   CARD_QUERY_CLASS,
   CARD_TARGET_STYLE_HREF,
+  CARD_HOVER_CLASS,
   CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
@@ -247,11 +248,23 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
-        {...(viewed
-          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
-          : {})}
+        // THE PHONE CARD SAYS IT IS A TARGET, TOO (D176). It carried no
+        // hover and no pressed state at all, and the device this card exists
+        // for answers `matchMedia("(hover: hover)")` with false — so a tap
+        // gave no feedback whatever until the next screen arrived. The shared
+        // class is one rule for a pointer that hovers and one for a finger
+        // that presses; `cardTargetCss` states both.
+        className={
+          viewed ? `${CARD_HOVER_CLASS} ${CARD_VIEWED_CLASS}` : CARD_HOVER_CLASS
+        }
+        {...(viewed ? { "data-listing-viewed": "true" } : {})}
         styles={{ body: { minWidth: 0, padding: token.paddingSM } }}
-        style={{ ["--listing-card-focus" as string]: token.colorPrimary }}
+        style={{
+          ["--listing-card-focus" as string]: token.colorPrimary,
+          // The corner the media well is cut to — see `cardTargetCss` (D180).
+          ["--listing-card-radius" as string]: `${String(token.borderRadiusLG)}px`,
+          ["--listing-card-hover-shadow" as string]: token.boxShadowSecondary,
+        }}
       >
         <div className={CARD_QUERY_CLASS}>
           <div className={CARD_FRAME_CLASS} style={{ gap: spacing[3] }}>