@stapel/listings-react 0.20.0 → 0.22.0

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/listings-react 0.20.0
+# @stapel/listings-react 0.22.0
 
-Headless React flow pair for stapel-listings (contract >=0.17 <0.18) — business + state, zero visual opinion.
+Headless React flow pair for stapel-listings (contract >=0.21 <0.22) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 
@@ -36,6 +36,7 @@ Paths are relative to `/listings/api/v1/`.
 - listings_api_v1_listings_retrieve: GET /listings/{id}/
 - listings_api_v1_listings_save_draft_create: POST /listings/{id}/save-draft/
 - listings_api_v1_listings_status_retrieve: GET /listings/{id}/status/
+- listings_api_v1_listings_transition_create: POST /listings/{id}/transition/
 - listings_api_v1_listings_unfavorite_create: POST /listings/{id}/unfavorite/
 - listings_api_v1_listings_update: PUT /listings/{id}/
 - listings_api_v1_listings_validate_draft_retrieve: GET /listings/{id}/validate-draft/
@@ -54,6 +55,7 @@ Paths are relative to `/listings/api/v1/`.
 - useMyFavorites (query) → myFavorites
 - usePublishListing (mutation) → publish
 - useSaveDraft (mutation) → saveDraft
+- useTransitionListing (mutation) → transition
 - useValidateDraft (query) → validateDraft
 
 ## Errors (render t(code, params); UX from remediation)

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/listings-react",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "backend": {
     "module": "stapel-listings",
-    "contract": ">=0.17 <0.18"
+    "contract": ">=0.21 <0.22"
   },
   "layers": [
     "api",
@@ -121,6 +121,13 @@
       "request": null,
       "response": "ListingStatus"
     },
+    "listings_api_v1_listings_transition_create": {
+      "method": "POST",
+      "path": "/listings/api/v1/listings/{id}/transition/",
+      "tag": "listings",
+      "request": "ListingTransitionRequest",
+      "response": "ListingActionResponse"
+    },
     "listings_api_v1_listings_unfavorite_create": {
       "method": "POST",
       "path": "/listings/api/v1/listings/{id}/unfavorite/",
@@ -263,6 +270,10 @@
       "kind": "mutation",
       "operation": "saveDraft"
     },
+    "useTransitionListing": {
+      "kind": "mutation",
+      "operation": "transition"
+    },
     "useValidateDraft": {
       "kind": "query",
       "operation": "validateDraft",
@@ -1058,11 +1069,17 @@
     "listings.mine.live_under_review",
     "listings.mine.load_failed",
     "listings.mine.loading",
+    "listings.mine.move.draft",
+    "listings.mine.move.paused",
+    "listings.mine.move.pending",
+    "listings.mine.move.published",
+    "listings.mine.move.renew",
     "listings.mine.retry",
     "listings.mine.tab.active",
     "listings.mine.tab.archived",
     "listings.mine.tab.drafts",
     "listings.mine.title",
+    "listings.mine.view",
     "listings.moderation.first_review",
     "listings.moderation.live_edit_pending",
     "listings.moderation.live_needs_review",
@@ -1123,6 +1140,7 @@
       "MY_LISTINGS_TAB_STATUSES",
       "MY_LISTINGS_UNTABBED_STATUSES",
       "MyListings",
+      "OWNER_TRANSITIONS",
       "PRICE_FIELD",
       "TITLE_FIELD",
       "asFeatureDaoList",
@@ -1164,6 +1182,7 @@
       "myListingPrice",
       "myListingTitle",
       "navEntries",
+      "ownerMoves",
       "pageKey",
       "publishRefusal",
       "registerListingsI18n",
@@ -1199,6 +1218,7 @@
       "useMyListings",
       "usePublishListing",
       "useSaveDraft",
+      "useTransitionListing",
       "useValidateDraft",
       "withEngagement"
     ],
@@ -1241,11 +1261,14 @@
       "ListingLifecycleStatus",
       "ListingLocation",
       "ListingModerationStatus",
+      "ListingMove",
+      "ListingOwnerTransition",
       "ListingPageKey",
       "ListingPageParams",
       "ListingStatusInfo",
       "ListingStatusTone",
       "ListingStatusView",
+      "ListingTransitionInput",
       "ListingsApi",
       "ListingsErrorCode",
       "ListingsErrorSpec",
@@ -1269,6 +1292,7 @@
       "SaveDraftInput",
       "Schemas",
       "UseFavoritesOptions",
+      "UseListingActionsOptions",
       "UseListingComposerOptions",
       "UseListingDetailOptions",
       "UseListingEngagementOverlayOptions",

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/listings-react",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "entries": [
     {
       "id": "listings.detail",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/listings-react",
-  "version": "0.20.0",
+  "version": "0.22.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,9 +53,9 @@
       "limit": "14 KB"
     },
     {
-      "name": "default — the antd skin (three cards, detail, composer, dashboard, the named slots and the delete confirmation) must stay out of the main bundle. Raised 17 -> 19 KB for the mobile wave: <ListingSerpCard> (photo strip + price-first block + action rail), <ListingFeedCard> and <FeedGrid> are two more card surfaces on the same shared target/favourite/photo parts, not three copies of one Raised 19 -> 20 KB for the desktop wave of the detail page: layout=\"split\" is a second ASSEMBLY of the money page (the sticky buy column, the two-column spec table, the widened measure) over the same parts, and GateReasonPopover is the blocked heart's third volume — the reason and the door disclosed on interaction, with the visually-hidden copy that keeps the refusal in the accessibility tree. Both are geometry and wiring, not new widgets. Raised 20 -> 21 KB (measured 20.22) for the engagement wave, which is four small things and no new component: the disclosure became a controlled open/close so a pointer that hovers and then clicks does not shut the only explanation the control has; the heart draws a filled accent when saved and states a failed save through the shared ErrorAlert; an already-seen card dims through one rule in the sheet all three cards already hoist; and the listing page gained a view-count row. 216 bytes is what a control that reports its own outcome costs",
+      "name": "default — the antd skin (three cards, detail, composer, dashboard, the named slots and the delete confirmation) must stay out of the main bundle. Raised 17 -> 19 KB for the mobile wave: <ListingSerpCard> (photo strip + price-first block + action rail), <ListingFeedCard> and <FeedGrid> are two more card surfaces on the same shared target/favourite/photo parts, not three copies of one Raised 19 -> 20 KB for the desktop wave of the detail page: layout=\"split\" is a second ASSEMBLY of the money page (the sticky buy column, the two-column spec table, the widened measure) over the same parts, and GateReasonPopover is the blocked heart's third volume — the reason and the door disclosed on interaction, with the visually-hidden copy that keeps the refusal in the accessibility tree. Both are geometry and wiring, not new widgets. Raised 20 -> 21 KB (measured 20.22) for the engagement wave, which is four small things and no new component: the disclosure became a controlled open/close so a pointer that hovers and then clicks does not shut the only explanation the control has; the heart draws a filled accent when saved and states a failed save through the shared ErrorAlert; an already-seen card dims through one rule in the sheet all three cards already hoist; and the listing page gained a view-count row. 216 bytes is what a control that reports its own outcome costs. Raised 21 -> 22 KB for the seller's board becoming a door in both directions: the transition route and useTransitionListing, OWNER_TRANSITIONS/ownerMoves as the fallback mirror, ListingActionsBag.moves drawn in a stable order, listingHref/linkComponent on the cabinet pane, the refusal that stops quoting the wire, and the row that fits a phone. Measured on a clean tree, this package's src reverted to the previous commit with dependencies held constant: 20.82 -> 21.60 KB. The old ceiling had 180 B of room and the work needs 780; none of it is copy, and a fourth axis of owner state is not a rounding error",
       "path": "dist/default/index.js",
-      "limit": "21 KB"
+      "limit": "22 KB"
     },
     {
       "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
@@ -103,12 +103,12 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@stapel/attributes-react": "^0.14.1",
-    "@stapel/core": "^0.23.1",
+    "@stapel/core": "^0.24.0",
     "@stapel/currencies-react": "^0.3.0",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.7.0",
-    "@stapel/tokens-antd": "^0.16.0"
+    "@stapel/tokens-antd": "^0.16.1"
   },
   "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.20.0",
+  "version": "0.22.0",
   "defined": [],
   "flows": []
 }

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",