@stapel/listings-react 0.21.0 → 0.22.0

package/src/i18n/ru.ts

@@ -53,8 +53,12 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "error.403.listing_not_owner": "Это не ваше объявление",
   "error.404.listing_not_found": "Объявление не найдено",
   "error.409.already_favorited": "Объявление уже в избранном",
+  // No `{from_status}`: what landed in that slot was the wire value
+  // ('draft', 'archived'), and the status is already named in the reader's
+  // own words beside the control. See the note on this pair of keys in
+  // keys.ts.
   "error.409.invalid_listing_transition":
-    "Объявление в статусе «{from_status}» так перевести нельзя",
+    "Из текущего состояния объявление так перевести нельзя",
   "error.409.listing_cannot_delete_active":
     "Сначала снимите объявление с публикации — активное удалить нельзя",
 
@@ -213,6 +217,12 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.mine.archive": "В архив",
   "listings.mine.complete": "Отметить проданным",
   "listings.mine.delete": "Удалить",
+  "listings.mine.move.published": "Опубликовать снова",
+  "listings.mine.move.pending": "Отправить на проверку",
+  "listings.mine.move.paused": "Снять с публикации",
+  "listings.mine.move.draft": "Вернуть в черновики",
+  "listings.mine.move.renew": "Продлить",
+  "listings.mine.view": "Посмотреть",
   "listings.mine.delete_confirm_title": "Удалить объявление?",
   "listings.mine.delete_confirm_body":
     "Оно исчезнет из кабинета, и вернуть его будет нельзя. Архив сохраняет его.",
@@ -240,7 +250,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.blocked.mandate_unknown":
     "Не удалось проверить ваш аккаунт, поэтому мы не угадываем, можно ли вам это",
   "listings.blocked.transition":
-    "Объявление в статусе «{from_status}» так перевести нельзя",
+    "Из текущего состояния объявление так перевести нельзя",
   "listings.blocked.delete_active":
     "Сначала уберите в архив — объявление в продаже удалить нельзя",
   "listings.blocked.in_flight": "Секунду — это уже выполняется",

package/src/index.ts

@@ -91,6 +91,7 @@ export type {
   ListingFeatureView,
   ListingLifecycleStatus,
   ListingModerationStatus,
+  ListingOwnerTransition,
   ListingPageParams,
   ListingStatusInfo,
   MyCounters,
@@ -120,7 +121,13 @@ export type {
   ModerationNotice,
   MyListingsTab,
 } from "./model/status.js";
-export { LISTING_TRANSITIONS, canDelete, canTransition } from "./model/transitions.js";
+export {
+  LISTING_TRANSITIONS,
+  OWNER_TRANSITIONS,
+  canDelete,
+  canTransition,
+  ownerMoves,
+} from "./model/transitions.js";
 
 // ── model: the owner's own rows ──────────────────────────────────────────────
 export { defaultMyListingsSource } from "./model/mineSource.js";
@@ -219,8 +226,13 @@ export {
   useFavoriteListing,
   usePublishListing,
   useSaveDraft,
+  useTransitionListing,
+} from "./model/mutations.js";
+export type {
+  FavoriteInput,
+  ListingTransitionInput,
+  SaveDraftInput,
 } from "./model/mutations.js";
-export type { FavoriteInput, SaveDraftInput } from "./model/mutations.js";
 
 // ── flows (zero-flow shim — stapel-listings annotates none) ──────────────────
 export { LISTINGS_FLOWS, flowEndpoints } from "./flows/registry.js";
@@ -275,7 +287,11 @@ export type {
   UseFavoritesOptions,
 } from "./headless/Favorites.js";
 export { useListingActions } from "./headless/ListingActions.js";
-export type { ListingActionsBag } from "./headless/ListingActions.js";
+export type {
+  ListingActionsBag,
+  ListingMove,
+  UseListingActionsOptions,
+} from "./headless/ListingActions.js";
 
 // ── nav manifest (the pair's public surface declaration) ─────────────────────
 export { ACCOUNT_ROOT_ID, navEntries } from "./nav/manifest.js";

package/src/model/mine.ts

@@ -68,3 +68,26 @@ export function myListingImages(row: MyListingCard): readonly string[] {
 export function showsDraft(row: MyListingCard): boolean {
   return empty(row.title) && !empty(row.title_draft);
 }
+
+/**
+ * Has this listing ever been in front of anybody?
+ *
+ * The server's own predicate, and it is the one that decides whether a row
+ * has a page to link to: `moderation_status` defaults to `NOT_SUBMITTED`
+ * (stapel-listings 0.20.0) and `publish_listing` sets `PENDING`
+ * unconditionally, so DRAFT + NOT_SUBMITTED means "nobody has ever pressed
+ * publish on this" and every other combination means somebody has.
+ *
+ * NOT {@link showsDraft}: that asks which HALF of the twin a row is showing,
+ * which is a different question and answers `false` for an empty draft that
+ * has no `title_draft` either — a row with no title at all would have been
+ * given a link to a page that does not exist.
+ *
+ * A row from a server older than 0.20.0 has no `moderation_status` of
+ * `not_submitted` to report, so it falls on the "has been submitted" side and
+ * keeps its link: an extra link to a draft its owner can read is a smaller
+ * harm than withholding one from a listing that is live.
+ */
+export function neverSubmitted(row: MyListingCard): boolean {
+  return row.status === "draft" && row.moderation_status === "not_submitted";
+}

package/src/model/mutations.ts

@@ -7,6 +7,7 @@ import type {
   ListingActionResponse,
   ListingDraft,
   ListingDraftPatch,
+  ListingOwnerTransition,
   PublishResponse,
 } from "../api/types.js";
 import { useListingsApi } from "./context.js";
@@ -162,6 +163,46 @@ export function useCompleteListing(): UseMutationResult<
   });
 }
 
+/** What a lifecycle move carries: the row, and where it is going. */
+export interface ListingTransitionInput {
+  readonly id: number;
+  readonly to: ListingOwnerTransition;
+}
+
+/**
+ * Move a listing along ONE edge of the seller's half of the state machine
+ * (`POST listings/{id}/transition/`, stapel-listings 0.20.0).
+ *
+ * The generalisation of {@link useArchiveListing} and
+ * {@link useCompleteListing}, and the reason it exists is that those two were
+ * the whole owner API for two releases: both are EXITS, so a listing that
+ * reached SOLD, ARCHIVED, PAUSED or EXPIRED had no call that would move it
+ * again and a cabinet honestly had nothing to offer but Delete. The way back
+ * — SOLD or PAUSED to PUBLISHED, ARCHIVED to DRAFT, EXPIRED renewed — was in
+ * `LISTING_TRANSITIONS` the entire time and simply had no route.
+ *
+ * Same 409 as the two named exits (`error.409.invalid_listing_transition`
+ * with `params.from_status`), and the same invalidation: a move changes which
+ * tab the row belongs to, so the counters and every `my/listings` page go
+ * with it.
+ */
+export function useTransitionListing(): UseMutationResult<
+  ListingActionResponse,
+  StapelApiError,
+  ListingTransitionInput
+> {
+  const api = useListingsApi();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (input: ListingTransitionInput) =>
+      api.transition(input.id, input.to),
+    retry: false,
+    onSuccess: (_data, input) => {
+      invalidateListing(queryClient, input.id);
+    },
+  });
+}
+
 /** Soft-delete. Refused with `error.409.listing_cannot_delete_active` while
  * the listing is PUBLISHED or PENDING. */
 export function useDeleteListing(): UseMutationResult<

package/src/model/status.ts

@@ -168,6 +168,11 @@ export function moderationNotice(
     return undefined;
   }
 
+  // NOTHING HAS BEEN SUBMITTED, so there is nothing for moderation to say.
+  // The lifecycle already calls this row a draft, and a second line beside
+  // that word can only add a claim the data does not support.
+  if (moderationStatus === "not_submitted") return undefined;
+
   if (moderationStatus === "pending") {
     if (live) {
       return {
@@ -207,15 +212,28 @@ export function moderationNotice(
     };
   }
 
-  // rejected — and it matters whether the lifecycle followed the verdict.
-  return {
-    moderationStatus,
-    messageKey: live
-      ? LISTINGS_I18N_KEYS.moderationRejectedStillLive
-      : LISTINGS_I18N_KEYS.moderationRejected,
-    tone: "warning",
-    liveDuringReview: live,
-  };
+  if (moderationStatus === "rejected") {
+    // …and it matters whether the lifecycle followed the verdict.
+    return {
+      moderationStatus,
+      messageKey: live
+        ? LISTINGS_I18N_KEYS.moderationRejectedStillLive
+        : LISTINGS_I18N_KEYS.moderationRejected,
+      tone: "warning",
+      liveDuringReview: live,
+    };
+  }
+
+  // AN UNKNOWN VALUE SAYS NOTHING. This used to be the `rejected` branch's
+  // fallthrough, which made "not one of the three I know" mean "a moderator
+  // turned this down" — and then stapel-listings 0.20.0 added a fourth value
+  // and made it the DEFAULT, so every freshly created draft in the cabinet
+  // was announced as "A moderator turned this listing down. Fix it and send
+  // it again." to a person who had submitted nothing (D166). A row read from a
+  // server newer than this pair must degrade to silence, never to a verdict:
+  // the lifecycle caption beside it is still true, and an accusation is the
+  // one thing a client must not invent.
+  return undefined;
 }
 
 /** Both halves at once — what a dashboard row and a detail header render. */

package/src/model/transitions.ts

@@ -44,7 +44,13 @@ export const LISTING_TRANSITIONS: Readonly<
 };
 
 /** Would the server accept this move? A same-status move is a no-op the
- * server returns early on, so it counts as allowed. */
+ * server returns early on, so it counts as allowed.
+ *
+ * "Accept" and "offer" are NOT the same question, and conflating them is the
+ * whole of defect D182: `canTransition("sold", "sold")` is true, so a SOLD
+ * row's "Mark sold" button was enabled, clickable, and did nothing — and so
+ * was an ARCHIVED row's "Archive". Ask {@link ownerMoves} what to OFFER.
+ */
 export function canTransition(
   from: ListingLifecycleStatus,
   to: ListingLifecycleStatus
@@ -52,6 +58,79 @@ export function canTransition(
   return from === to || LISTING_TRANSITIONS[from].includes(to);
 }
 
+/**
+ * The SELLER's half of the machine above, mirrored from
+ * `stapel_listings.models.OWNER_TRANSITIONS` (0.20.0).
+ *
+ * A subset of {@link LISTING_TRANSITIONS}, and what it leaves out is as
+ * load-bearing as what it keeps: `pending → published` and
+ * `blocked → published` are moderation's decisions, `published → blocked` is
+ * a takedown, and none of the three is a thing one does to oneself. Putting
+ * them here would make the cabinet a self-service publish gate.
+ *
+ * ── This is a FALLBACK, and the card's own field is the answer ─────────────
+ *
+ * `MyListingCard.available_transitions` is the server reporting this table
+ * for one row, and where it is present nothing here is consulted: the set a
+ * client offers and the set the route accepts are then one object rather than
+ * two that agree today. This copy is for a surface that holds only a `status`
+ * — a detail pane, a listing loaded before 0.20.0 — where the alternative is
+ * offering nothing at all.
+ */
+export const OWNER_TRANSITIONS: Readonly<
+  Record<ListingLifecycleStatus, readonly ListingLifecycleStatus[]>
+> = {
+  draft: ["pending", "archived"],
+  pending: ["draft", "archived"],
+  published: ["paused", "sold", "archived"],
+  paused: ["published", "archived"],
+  expired: ["pending", "archived"],
+  sold: ["published", "archived"],
+  rejected: ["draft", "archived"],
+  blocked: ["draft", "archived"],
+  archived: ["draft"],
+};
+
+/**
+ * The order the moves are DRAWN in, wherever they came from.
+ *
+ * A row's action set changes as the listing moves through its life, and a set
+ * that also reorders itself makes a person hunt for the button they used
+ * yesterday. Forward first (back on sale, then submitted, then paused), exits
+ * last — so "Archive" is never where "Publish again" was a moment ago.
+ */
+const MOVE_ORDER: readonly ListingLifecycleStatus[] = [
+  "published",
+  "pending",
+  "paused",
+  "sold",
+  "draft",
+  "rejected",
+  "blocked",
+  "expired",
+  "archived",
+];
+
+/**
+ * What to OFFER a seller looking at a row in *status*, in drawing order.
+ *
+ * Never the status the row is already in: a control that would leave the
+ * world exactly as it found it is not an action, and four of them down a
+ * dashboard taught a seller that half the buttons on this screen do nothing.
+ *
+ * Pass the card's own `available_transitions` when it has one — see
+ * {@link OWNER_TRANSITIONS} for why the mirror is the second-best answer.
+ */
+export function ownerMoves(
+  status: ListingLifecycleStatus | undefined,
+  available?: readonly ListingLifecycleStatus[] | undefined
+): readonly ListingLifecycleStatus[] {
+  if (status === undefined) return [];
+  const offered = available ?? OWNER_TRANSITIONS[status];
+  const set = new Set(offered.filter((to) => to !== status));
+  return MOVE_ORDER.filter((to) => set.has(to));
+}
+
 /**
  * Deleting is not a transition and has its own rule
  * (`views.destroy`): a PUBLISHED or PENDING listing is refused with