@stapel/listings-react 0.3.0 → 0.4.0

package/src/api/generated/schema.ts

@@ -42,7 +42,9 @@ export interface paths {
          */
         get: operations["listings_api_v1_listings_retrieve"];
         /**
-         * @description Listings CRUD plus owner lifecycle actions and favorites.
+         * @description Write the draft fields — the write ``save-draft`` also performs.
+         *
+         *     Owner only: 404 for an absent listing, 403 for someone else's.
          *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
@@ -274,6 +276,37 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/listings/api/v1/listings/my/listings/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description The caller's OWN listings, in every status.
+         *
+         *     The counterpart of ``my/counters``: the same owner scope and the same
+         *     status grouping, but the rows behind the three numbers. ``list`` is
+         *     the shop window (``published()``, narrowable to nobody), so this is
+         *     the only route by which a person can be shown their own drafts.
+         *
+         *     Owner-scoped at the queryset via ``owned_by`` — a stranger's listing
+         *     cannot be reached from here at any status, and soft-deleted rows are
+         *     excluded by the default manager (a deleted listing is gone from the
+         *     owner's dashboard exactly as it is gone from everywhere else).
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        get: operations["listings_api_v1_listings_my_listings_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -673,6 +706,58 @@ export interface components {
             archived: number;
             drafts: number;
         };
+        /**
+         * @description The owner's own card — the public card plus what only an owner sees.
+         *
+         *     Same family as :class:`ListingCardSerializer` (one shape for every grid a
+         *     product renders), extended along two axes and no further:
+         *
+         *     - **the moderation axis** (``moderation_status``): visibility is decided
+         *       by ``status`` alone, but since 0.5.0 a *published* listing can be under
+         *       re-review, and its owner is the one person who has to be told. A
+         *       dashboard cannot derive that sentence from ``status``.
+         *     - **the draft twins** (``title_draft`` / ``price_draft`` /
+         *       ``images_draft``): the published fields are empty on a listing that has
+         *       never been published, so a drafts tab built on the public card would
+         *       render a column of blank rows. This is the list half of the pair's
+         *       upstream ask #2 — the detail read is unchanged and still serializes the
+         *       published fields only.
+         *
+         *     Owner-scoped by construction: this serializer is used by exactly one
+         *     route, ``my/listings``, whose queryset is ``owned_by(request.user)``.
+         */
+        MyListingCard: {
+            readonly id: number;
+            title?: string;
+            /** Format: decimal */
+            price?: string;
+            /** Format: decimal */
+            price_base?: string | null;
+            currency?: string;
+            readonly images: string[] | null;
+            readonly features_title: components["schemas"]["FeatureDao"][];
+            readonly features_badges: components["schemas"]["FeatureDao"][];
+            location_label?: string;
+            geohash?: string;
+            /** Format: decimal */
+            lat?: string | null;
+            /** Format: decimal */
+            lon?: string | null;
+            countable?: boolean;
+            /** Format: int64 */
+            stock_quantity?: number | null;
+            status?: components["schemas"]["StatusD41Enum"];
+            readonly is_favorited: boolean | null;
+            moderation_status?: components["schemas"]["ModerationStatusEnum"];
+            title_draft?: string;
+            /** Format: decimal */
+            price_draft?: string | null;
+            readonly images_draft: string[] | null;
+            /** Format: date-time */
+            readonly created_at: string;
+            /** Format: date-time */
+            readonly updated_at: string;
+        };
         /** @enum {unknown} */
         NullEnum: null;
         PaginatedListingCardList: {
@@ -688,6 +773,19 @@ export interface components {
             /** @description Number of items in current page */
             count: number;
         };
+        PaginatedMyListingCardList: {
+            items: components["schemas"]["MyListingCard"][];
+            /** @description Anchor value for next page */
+            next_anchor?: string | null;
+            /** @description Anchor value for previous page */
+            prev_anchor?: string | null;
+            /** @description Whether there are more items after this page */
+            has_next: boolean;
+            /** @description Whether there are items before this page */
+            has_prev: boolean;
+            /** @description Number of items in current page */
+            count: number;
+        };
         /**
          * @description Create/update the draft twin fields.
          *
@@ -1252,4 +1350,32 @@ export interface operations {
             };
         };
     };
+    listings_api_v1_listings_my_listings_list: {
+        parameters: {
+            query?: {
+                /** @description Anchor value to paginate from (exclusive) */
+                anchor?: string;
+                /** @description Pagination direction */
+                direction?: "next" | "prev" | "center";
+                /** @description Number of items (default 100, max 1000) */
+                limit?: number;
+                /** @description Lifecycle status to narrow to. Repeat the parameter or pass one comma-separated value for a set (`?status=draft,rejected`); omit it for every status. An unknown value is a 400, not an empty page. */
+                status?: ("archived" | "blocked" | "draft" | "expired" | "paused" | "pending" | "published" | "rejected" | "sold")[];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedMyListingCardList"];
+                };
+            };
+        };
+    };
 }

package/src/api/listingsApi.ts

@@ -9,7 +9,9 @@ import type {
   ListingPageParams,
   ListingStatusInfo,
   MyCounters,
+  MyListingsParams,
   PaginatedListingCards,
+  PaginatedMyListingCards,
   PublishResponse,
 } from "./types.js";
 import type { ValidationBatchResult } from "@stapel/attributes-react";
@@ -22,21 +24,16 @@ import type { ValidationBatchResult } from "@stapel/attributes-react";
  *
  * ── The two operations that are on the contract and NOT here ───────────────
  *
- * `PUT /{pk}/` and `PATCH /{pk}/` are absent, and this is the one place in
- * the pair where an absence is a safety decision rather than a scope one.
- * Every OWNER operation in this module routes through `views._get_own`, which
- * answers `error.403.listing_not_owner` when the caller is not the owner —
- * every one except these two. `update`/`partial_update` are the plain
- * `ModelViewSet` implementations under the viewset's default
- * `IsAuthenticatedOrReadOnly`, and `get_queryset` hands them
- * `Listing.objects.all()`: any authenticated caller can write any listing's
- * draft fields through them. `POST /{pk}/save-draft/` performs the SAME write
- * (the same `ListingDraftSerializer`, `partial=True`) with the ownership
- * check, so the pair uses it and nothing is lost. Both stay in the generated
- * schema and therefore in `manifest.json` — the contract is not hidden, this
- * pair simply declines to be the client that exercises it. Upstream ask,
- * recorded in MODULE.md: put `_get_own` in front of `update`/`partial_update`
- * (or drop them from the router).
+ * `PUT /{pk}/` and `PATCH /{pk}/` are absent. That began as a safety decision:
+ * until stapel-listings 0.6.2 both were the plain `ModelViewSet`
+ * implementations under `IsAuthenticatedOrReadOnly` over
+ * `Listing.objects.all()`, so any authenticated caller could write any
+ * listing's draft fields through them — this pair filed the ask and declined
+ * to be the client that exercised the hole. 0.6.2 put `views._get_own` in
+ * front of both, so the hole is closed and the absence is now a plain scope
+ * decision: `POST /{pk}/save-draft/` performs the SAME write (the same
+ * `ListingDraftSerializer`, `partial=True`) and one write path is enough.
+ * Both stay in the generated schema and therefore in `manifest.json`.
  *
  * These operations will be GENERATED from schema.json operationIds by gen-api
  * v2 (task `core-typed-ops`); until then they are hand-authored here (the ONE
@@ -70,12 +67,12 @@ export interface ListingsApi {
   /**
    * One listing in full.
    *
-   * `IsAuthenticatedOrReadOnly` + a queryset with no `published()` filter:
-   * this answers for a DRAFT and for a BLOCKED listing too, to anyone who
-   * knows the id. The pair does not pretend otherwise — `useListing` reports
-   * `publiclyVisible` off `status` so a skin can say "this listing is not
-   * published" instead of drawing a live-looking page (see `model/status.ts`,
-   * and MODULE.md's upstream note).
+   * Since 0.6.2 the queryset is `visible_to(user)` — the indexed statuses for
+   * everyone plus one's OWN rows in any status — so a stranger's draft 404s
+   * from the same code path an absent id does. The `publiclyVisible` report
+   * `useListing` derives from `status` (`model/status.ts`) stays, and is now
+   * addressed at the one reader who still reaches an unpublished listing
+   * here: its owner, who needs to be told it is not on the shelf.
    */
   retrieve(
     id: number,
@@ -100,6 +97,26 @@ export interface ListingsApi {
    * PENDING in with PUBLISHED, `drafts` folds REJECTED in with DRAFT. */
   myCounters(options?: { readonly signal?: AbortSignal }): Promise<MyCounters>;
 
+  /**
+   * One keyset page of the caller's OWN listings, in every status.
+   *
+   * The route `list` is not and cannot be made into: `list` answers
+   * `published()` and takes no owner parameter, so before stapel-listings
+   * 0.7.0 a seller's own DRAFTS were unreachable by any call this contract
+   * offered — the gap `model/mineSource.ts` used to name on screen. Owner
+   * scope is a property of the ROUTE (`owned_by(request.user)`), not of a
+   * parameter a caller supplies, so there is no way to point it at anyone
+   * else.
+   *
+   * `params.status` narrows to a set of lifecycle statuses; omit it for all
+   * nine. Rows are {@link MyListingCard} — the public card plus
+   * `moderation_status` and the `*_draft` twins.
+   */
+  myListings(
+    params?: MyListingsParams,
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<PaginatedMyListingCards>;
+
   /** One keyset page of the caller's favourites. */
   myFavorites(
     params?: ListingPageParams,
@@ -182,6 +199,22 @@ function pageQuery(
   };
 }
 
+/**
+ * The `?status=` half of a `my/listings` query.
+ *
+ * One comma-separated value rather than a repeated parameter: both spellings
+ * are accepted upstream, and this one survives every `query` serializer a
+ * host's `StapelClient` might carry without depending on how it encodes an
+ * array. An empty set sends nothing at all — the route's own "every status".
+ */
+function statusQuery(
+  statuses: readonly string[] | undefined
+): Record<string, string> {
+  return statuses !== undefined && statuses.length > 0
+    ? { status: statuses.join(",") }
+    : {};
+}
+
 function signal(
   options: { readonly signal?: AbortSignal } | undefined
 ): { signal?: AbortSignal } {
@@ -209,6 +242,12 @@ export function createListingsApi(client: StapelClient): ListingsApi {
     myCounters: (options) =>
       client.get(`${COLLECTION}my/counters/`, signal(options)),
 
+    myListings: (params, options) =>
+      client.get(`${COLLECTION}my/listings/`, {
+        query: { ...pageQuery(params), ...statusQuery(params?.status) },
+        ...signal(options),
+      }),
+
     myFavorites: (params, options) =>
       client.get(`${COLLECTION}my/favorites/`, {
         query: pageQuery(params),

package/src/api/types.ts

@@ -72,9 +72,34 @@ export type FavoriteToggleResponse = Schemas["FavoriteToggleResponse"];
 /** `DELETE /{pk}/` 200. */
 export type DeleteResponse = Schemas["DeleteResponse"];
 
-/** The keyset envelope both card lists come back in (`IDAnchorPagination`). */
+/** The keyset envelope both public card lists come back in
+ * (`IDAnchorPagination`). */
 export type PaginatedListingCards = Schemas["PaginatedListingCardList"];
 
+/**
+ * One row of `GET /listings/my/listings/` — the OWNER's card.
+ *
+ * A superset of {@link ListingCard}, and the two additions are the two things
+ * only an owner is owed (stapel-listings 0.7.0, `MyListingCardSerializer`):
+ *
+ *  - `moderation_status`, the second axis. `model/status.ts` argues at length
+ *    that a dashboard cannot derive "your edit is being screened" from
+ *    `status` — a re-published LIVE listing keeps `status: "published"` and
+ *    moves only this field. The public card omits it, so before 0.7.0 the
+ *    dashboard row passed `"approved"` as an honest stand-in and simply could
+ *    not show the row that most needed showing.
+ *  - the `*_draft` twins. `title`/`price`/`images` are the PUBLISHED fields
+ *    and are empty on a listing that has never been published, so a drafts
+ *    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 = Schemas["MyListingCard"];
+
+/** The keyset envelope `GET /listings/my/listings/` comes back in — the same
+ * `IDAnchorPagination` shape as {@link PaginatedListingCards}, over the owner
+ * row. */
+export type PaginatedMyListingCards = Schemas["PaginatedMyListingCardList"];
+
 /**
  * The nine lifecycle states, as `models.ListingStatus` declares them.
  *
@@ -173,7 +198,7 @@ export interface ListingFeatureView {
  * `@stapel/attributes-react` directly. */
 export type { FeatureConfig, FeatureDef, FeatureValueDto };
 
-/** Query parameters of both keyset-paginated card lists. */
+/** Query parameters of every keyset-paginated card list. */
 export interface ListingPageParams {
   /** Opaque cursor from a previous answer. */
   readonly anchor?: string;
@@ -181,6 +206,25 @@ export interface ListingPageParams {
   readonly limit?: number;
 }
 
+/**
+ * `GET /listings/my/listings/` — a page, plus the statuses to narrow to.
+ *
+ * `status` is a SET because a dashboard tab is one (`active` is
+ * `published` + `pending`, `drafts` is `draft` + `rejected` — the groupings
+ * are the server's, copied in `model/status.ts` so a tab's rows and its count
+ * cannot describe different sets). An empty or absent array means every
+ * status, which is what the route answers with no parameter at all.
+ *
+ * On the wire it goes as one comma-separated value; stapel-listings accepts
+ * that and the repeated-parameter spelling interchangeably
+ * (`views.parse_status_filter`). An unknown value is a `400`
+ * `error.400.listing_invalid_status_filter`, not an empty page — so a status
+ * this pair does not know about cannot silently look like "you have none".
+ */
+export interface MyListingsParams extends ListingPageParams {
+  readonly status?: readonly ListingLifecycleStatus[];
+}
+
 /**
  * The currency a composer starts a new listing in.
  *

package/src/default/ListingDetailPane.tsx

@@ -246,9 +246,14 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               ) : null}
 
               <Descriptions size="small" column={1}>
+                {/* Label cell and value cell, which is what a `<Descriptions>`
+                    row IS: the label key carries no `{count}` (it did, and the
+                    page printed the placeholder), the quantity is the value. */}
                 {listing.stock_quantity != null ? (
                   <Descriptions.Item label={t(LISTINGS_I18N_KEYS.detailStock)}>
-                    {listing.stock_quantity}
+                    <span data-testid="listings-detail-stock">
+                      {listing.stock_quantity}
+                    </span>
                   </Descriptions.Item>
                 ) : null}
                 {listing.location_label !== undefined &&

package/src/default/MyListingsPane.tsx

@@ -1,16 +1,29 @@
 /**
  * `<MyListingsPane>` — the seller's dashboard.
  *
- * Three counts that are real, and rows that may not be: stapel-listings 0.6.1
- * has no owner-scoped list endpoint (`headless/MyListings.tsx` argues it in
- * full), so the rows come from an injected source and the pane NAMES the gap
- * when there is none. The counters are shown either way, because they are the
- * one thing the contract can actually answer.
+ * Three counts and the rows behind them, both real since stapel-listings
+ * 0.7.0 gave the owner's own listings a route (`GET my/listings/`). Until
+ * then this pane showed the counts and NAMED the missing endpoint where the
+ * rows should be; `model/mineSource.ts` keeps that history and the seam it
+ * left behind.
  *
- * Each row carries both axes. "Published" and "changes under review" appear
- * beside each other, which is the entire reason `model/status.ts` exists: a
- * dashboard that derived one from the other would tell a seller their live
- * listing is offline, or never tell them their edit is being screened.
+ * Three things this pane refuses to smooth over:
+ *
+ * 1. **Both axes on every row.** "Published" and "changes under review" appear
+ *    beside each other, which is the entire reason `model/status.ts` exists: a
+ *    dashboard that derived one from the other would tell a seller their live
+ *    listing is offline, or never tell them their edit is being screened.
+ *    `moderation_status` is on the owner card, so the row reads the real
+ *    value rather than the `"approved"` stand-in it used before 0.7.0.
+ * 2. **Takedowns are not in a tab.** The three tabs are the SERVER's status
+ *    groupings and `blocked` is in none of them, because `my/counters` counts
+ *    it in none of them. Folding it into one would make a tab's rows and its
+ *    badge describe different sets; leaving it out entirely would hide the
+ *    one listing whose owner most needs to know. So it sits above the tabs,
+ *    where it cannot be missed.
+ * 3. **An empty tab says which emptiness it is.** "No drafts" and "nothing
+ *    sold yet" are different sentences and one generic "nothing here" is
+ *    neither.
  */
 import type { ReactElement } from "react";
 import {
@@ -28,10 +41,11 @@ import {
 } from "antd";
 import { matchList, matchLoad, useDescribeFlowError, useT } from "@stapel/core";
 import type { ActionAvailability } from "@stapel/core";
-import type { ListingCard as ListingCardData } from "../api/types.js";
+import type { MyListingCard } from "../api/types.js";
 import { useMyListings } from "../headless/MyListings.js";
 import type { MyListingsSource } from "../model/mineSource.js";
 import { useListingActions } from "../headless/ListingActions.js";
+import { myListingTitle, showsDraft } from "../model/mine.js";
 import { listingStatusView } from "../model/status.js";
 import type { MyListingsTab } from "../model/status.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
@@ -46,6 +60,13 @@ const TAB_LABEL: Readonly<Record<MyListingsTab, string>> = {
   archived: LISTINGS_I18N_KEYS.mineTabArchived,
 };
 
+/** One empty sentence per tab — see the header, point 3. */
+const TAB_EMPTY: Readonly<Record<MyListingsTab, string>> = {
+  active: LISTINGS_I18N_KEYS.mineEmptyActive,
+  drafts: LISTINGS_I18N_KEYS.mineEmptyDrafts,
+  archived: LISTINGS_I18N_KEYS.mineEmptyArchived,
+};
+
 /** A control plus the sentence that explains it when it is off. Written once
  * here because this pane has six of them and a grey button with no reason is
  * the one shape `ActionAvailability` exists to make impossible. */
@@ -89,21 +110,24 @@ function GatedButton(props: {
 }
 
 function MyListingRow(props: {
-  listing: ListingCardData;
+  listing: MyListingCard;
   onEdit?: (id: number) => void;
 }): ReactElement {
   const t = useT();
   const describe = useDescribeFlowError();
   const actions = useListingActions(props.listing.id, props.listing.status);
-  // The card list carries `status` but NOT `moderation_status`
-  // (`ListingCardSerializer` omits it), so a row shows the moderation axis
-  // only through the one thing the projection does say. Pending is the
-  // honest default for the notice table's second argument here: it is the
-  // value that produces a note only when the lifecycle also implies one.
+  // Both axes, both real: `MyListingCardSerializer` puts `moderation_status`
+  // on the owner's card, so the row no longer has to pass "approved" as a
+  // stand-in and lose the one combination that matters — a LIVE listing whose
+  // edit is under review.
   const status =
     props.listing.status === undefined
       ? undefined
-      : listingStatusView(props.listing.status, "approved");
+      : listingStatusView(
+          props.listing.status,
+          props.listing.moderation_status ?? "approved"
+        );
+  const heading = myListingTitle(props.listing);
 
   return (
     <List.Item
@@ -152,7 +176,19 @@ function MyListingRow(props: {
       ]}
     >
       <List.Item.Meta
-        title={props.listing.title ?? String(props.listing.id)}
+        title={
+          <Space size={6}>
+            {heading ?? `#${String(props.listing.id)}`}
+            {/* A heading that came off the draft twin is something nobody
+                else can read yet. Saying so is the difference between a
+                dashboard and a shop window that happens to be yours. */}
+            {showsDraft(props.listing) ? (
+              <Typography.Text type="secondary" data-testid="listings-mine-draft-title">
+                {t(LISTINGS_I18N_KEYS.statusDraft)}
+              </Typography.Text>
+            ) : null}
+          </Space>
+        }
         description={
           <Flex vertical gap={4}>
             {status !== undefined ? <ListingStatusBlock status={status} /> : null}
@@ -176,8 +212,8 @@ function MyListingRow(props: {
 }
 
 export interface MyListingsPaneProps extends ThemeModeProp {
-  /** How the host gets the caller's own rows. Absent: the pane says the
-   * contract cannot answer, and still shows the counts. */
+  /** How the host gets the caller's own rows. Absent: the contract's own
+   * `GET my/listings/`, which is what a storefront wants. */
   readonly source?: MyListingsSource;
   readonly onEdit?: (id: number) => void;
 }
@@ -205,6 +241,46 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
           />
         ) : null}
 
+        {/* The rows no tab folds in — see the header, point 2. Rendered
+            only when there are some: an empty takedown section is a scare,
+            and a failure to CHECK is not the same as "none", so it says so. */}
+        {matchList(bag.blockedRows, {
+          loading: () => null,
+          failed: () => (
+            <Typography.Text
+              type="secondary"
+              data-testid="listings-mine-takedowns-failed"
+            >
+              {t(LISTINGS_I18N_KEYS.mineBlockedLoadFailed)}
+            </Typography.Text>
+          ),
+          empty: () => null,
+          ready: (rows) => (
+            <Alert
+              type="error"
+              showIcon
+              data-testid="listings-mine-takedowns"
+              message={t(LISTINGS_I18N_KEYS.mineBlockedTitle, {
+                count: rows.length,
+              })}
+              description={
+                <List
+                  dataSource={[...rows]}
+                  rowKey={(row) => row.id}
+                  renderItem={(row) => (
+                    <MyListingRow
+                      listing={row}
+                      {...(props.onEdit !== undefined
+                        ? { onEdit: props.onEdit }
+                        : {})}
+                    />
+                  )}
+                />
+              }
+            />
+          ),
+        })}
+
         <Tabs
           activeKey={bag.tab}
           data-testid="listings-mine-tabs"
@@ -275,7 +351,8 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
           empty: () => (
             <Empty
               data-testid="listings-mine-empty"
-              description={t(LISTINGS_I18N_KEYS.mineEmpty)}
+              data-empty-tab={bag.tab}
+              description={t(TAB_EMPTY[bag.tab])}
             />
           ),
           ready: (rows) => (
@@ -292,19 +369,6 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
           ),
         })}
 
-        {/* The named gap. `matchList`'s `failed` arm above already renders
-            "we could not load"; this states WHY once, in the pane, because
-            the reason is a property of this deployment and not of this
-            request. */}
-        {props.source === undefined ? (
-          <Alert
-            type="warning"
-            showIcon
-            data-testid="listings-mine-source-missing"
-            message={t(LISTINGS_I18N_KEYS.mineSourceMissing)}
-          />
-        ) : null}
-
         <Space>
           <Button
             size="small"