@stapel/listings-react 0.1.0

package/src/model/runtime.ts

@@ -0,0 +1,87 @@
+import { createModuleRuntime } from "@stapel/core";
+import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { StapelImage } from "@stapel/image";
+import { createListingsApi } from "../api/listingsApi.js";
+import type { ListingsApi } from "../api/listingsApi.js";
+import { DEFAULT_LISTING_CURRENCY } from "../api/types.js";
+import { DEFAULT_DRAFT_LIMITS } from "./validation.js";
+import type { ListingDraftLimits } from "./validation.js";
+
+/**
+ * Turn a stored image reference into something renderable.
+ *
+ * ── Why this is a seam and not a URL builder ───────────────────────────────
+ *
+ * `Listing.images` is a list of OPAQUE CDN references (`<type>/<hash>`), and
+ * the listings contract offers no way to resolve one: there is no
+ * `GET /listings/{pk}/images/`, and stapel-cdn's `file/exists/` is
+ * owner-scoped (`uploaded_by=request.user`), so `@stapel/cdn-react`'s
+ * `useCdnRef` can resolve a person's OWN draft and can never render a
+ * stranger's gallery — it says so itself. There is therefore no public
+ * read-by-reference anywhere in this fleet's contracts today.
+ *
+ * The honest answer is a seam, not an invented URL convention: a deployment
+ * knows where its CDN serves from, and hands that knowledge in once. A pair
+ * that guessed `${cdnBase}/${ref}` would be writing a contract nobody agreed
+ * to, and it would break the first host that puts a signature on the path.
+ *
+ * Returning a full `StapelImage` rather than a string is what buys the
+ * variant ladder: with `variants` populated, `@stapel/image`'s `<Image>`
+ * measures the slot and picks a tier; with only `url`, it shows that one.
+ * Both are supported, and a resolver that has nothing for a reference returns
+ * `undefined` — the skin then says "photo unavailable" instead of drawing a
+ * broken `<img>`. Recorded as an upstream gap in MODULE.md.
+ */
+export type ListingImageResolver = (ref: string) => StapelImage | undefined;
+
+export interface CreateListingsRuntimeOptions
+  extends CreateModuleRuntimeOptions {
+  /** See {@link ListingImageResolver}. Absent = no gallery is drawn, and the
+   * skin names the reason. */
+  readonly resolveImage?: ListingImageResolver;
+  /**
+   * The deployment's own ceilings, mirrored client-side. Partial: only the
+   * ones that differ from `stapel_listings/conf.py`'s library defaults.
+   */
+  readonly limits?: Partial<ListingDraftLimits>;
+  /** Currency a new draft starts in. Owner verdict F6: RUB. */
+  readonly currency?: string;
+}
+
+/**
+ * The wired listings runtime — core's `ModuleRuntime` bound to this pair's
+ * API (slim wave §21/S2), plus the three pieces of deployment knowledge the
+ * pair cannot derive: how to render a reference, where the ceilings are, and
+ * what currency the shop trades in.
+ *
+ * ```tsx
+ * const runtime = createListingsRuntime({
+ *   baseUrl: "/listings/api/v1/",
+ *   resolveImage: (ref) => myCdn.describe(ref),
+ * });
+ * <ListingsProvider runtime={runtime}>…</ListingsProvider>
+ * ```
+ *
+ * NOT session-gated as a whole. The public reads (`retrieve`, `status`,
+ * `list`) are `IsAuthenticatedOrReadOnly` and answer a visitor who will never
+ * sign in; the owner reads and every write are `IsAuthenticated` and the
+ * hooks that call them gate on `useActiveSessionReady` individually. Gating
+ * the module would make a shop window wait for a login bootstrap.
+ */
+export interface ListingsRuntime extends ModuleRuntime<ListingsApi> {
+  readonly resolveImage: ListingImageResolver | undefined;
+  readonly limits: ListingDraftLimits;
+  readonly currency: string;
+}
+
+export function createListingsRuntime(
+  options: CreateListingsRuntimeOptions
+): ListingsRuntime {
+  const base = createModuleRuntime((client) => createListingsApi(client), options);
+  return {
+    ...base,
+    resolveImage: options.resolveImage,
+    limits: { ...DEFAULT_DRAFT_LIMITS, ...options.limits },
+    currency: options.currency ?? DEFAULT_LISTING_CURRENCY,
+  };
+}

package/src/model/status.ts

@@ -0,0 +1,279 @@
+/**
+ * TWO AXES, BOTH ON SCREEN, NEITHER STANDING IN FOR THE OTHER.
+ *
+ * `status` (nine states) is the lifecycle and the ONLY thing that decides
+ * whether a listing is public: `Listing.objects.published()` filters on it
+ * alone, `INDEXED_STATUSES` is `{published}`, and the model says so out loud
+ * ("no visibility-reads-moderation_status coupling", `models.py`).
+ * `moderation_status` (four states) is the content verdict and decides
+ * NOTHING about visibility.
+ *
+ * Since stapel-listings 0.5.0 the two genuinely diverge, and that divergence
+ * is the reason this file exists:
+ *
+ *   first publication      status draft   → PENDING,   moderation → pending
+ *                          (nothing public until a verdict arrives)
+ *   editing a LIVE listing status published (UNCHANGED), moderation → pending
+ *                          (the edit is visible immediately; a rejecting
+ *                           verdict later lands as PUBLISHED → BLOCKED)
+ *
+ * A dashboard that computed "under re-review" from `status` would show
+ * nothing at all for the second row — the listing looks exactly as it did —
+ * and the owner would never learn their edit is being screened. A dashboard
+ * that computed "visible" from `moderation_status` would tell them their live
+ * listing is offline while strangers are reading it. Both mistakes are one
+ * `if` away, which is why the sentence a person reads is produced HERE, from
+ * BOTH fields, once.
+ *
+ * Everything below is pure: no React, no antd, no fetch. `test/status.test.ts`
+ * asserts the whole 9 × 4 table, so a state added upstream is a red test and
+ * not a bare enum value on a page.
+ */
+import type {
+  ListingLifecycleStatus,
+  ListingModerationStatus,
+} from "../api/types.js";
+import { LISTING_TRANSITIONS } from "./transitions.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+
+/**
+ * How a status should READ, independent of the words: neutral (nothing is
+ * happening), waiting (something is in progress and needs no action), good
+ * (live), warning (the owner has something to do), stopped (the listing is
+ * over, by choice or by verdict).
+ *
+ * A tone rather than a colour: `/default` maps it to antd tags, another skin
+ * maps it to whatever it maps it to, and the token layer stays the only place
+ * a hex exists.
+ */
+export type ListingStatusTone =
+  | "neutral"
+  | "waiting"
+  | "good"
+  | "warning"
+  | "stopped";
+
+/** The lifecycle half of what a person is told. */
+export interface LifecycleCaption {
+  readonly status: ListingLifecycleStatus;
+  readonly labelKey: string;
+  readonly tone: ListingStatusTone;
+  /** Is the listing readable by a stranger right now? `published` and
+   * nothing else — the same predicate the queryset uses. */
+  readonly publiclyVisible: boolean;
+}
+
+const LIFECYCLE: Readonly<
+  Record<ListingLifecycleStatus, Omit<LifecycleCaption, "status">>
+> = {
+  draft: {
+    labelKey: LISTINGS_I18N_KEYS.statusDraft,
+    tone: "neutral",
+    publiclyVisible: false,
+  },
+  pending: {
+    labelKey: LISTINGS_I18N_KEYS.statusPending,
+    tone: "waiting",
+    publiclyVisible: false,
+  },
+  published: {
+    labelKey: LISTINGS_I18N_KEYS.statusPublished,
+    tone: "good",
+    publiclyVisible: true,
+  },
+  paused: {
+    labelKey: LISTINGS_I18N_KEYS.statusPaused,
+    tone: "neutral",
+    publiclyVisible: false,
+  },
+  expired: {
+    labelKey: LISTINGS_I18N_KEYS.statusExpired,
+    tone: "warning",
+    publiclyVisible: false,
+  },
+  sold: {
+    labelKey: LISTINGS_I18N_KEYS.statusSold,
+    tone: "stopped",
+    publiclyVisible: false,
+  },
+  rejected: {
+    labelKey: LISTINGS_I18N_KEYS.statusRejected,
+    tone: "warning",
+    publiclyVisible: false,
+  },
+  blocked: {
+    labelKey: LISTINGS_I18N_KEYS.statusBlocked,
+    tone: "stopped",
+    publiclyVisible: false,
+  },
+  archived: {
+    labelKey: LISTINGS_I18N_KEYS.statusArchived,
+    tone: "neutral",
+    publiclyVisible: false,
+  },
+};
+
+/** The lifecycle caption for one status. */
+export function lifecycleCaption(
+  status: ListingLifecycleStatus
+): LifecycleCaption {
+  return { status, ...LIFECYCLE[status] };
+}
+
+/**
+ * Is this listing readable by someone who is not its owner?
+ *
+ * One predicate, one field, matching the server's. Exported because the
+ * DETAIL read needs it and cannot get it from a 404: `GET /listings/{pk}/`
+ * has no `published()` filter on its queryset, so a draft answers 200 to a
+ * stranger who knows the id (upstream note in MODULE.md). The pair reports
+ * the fact instead of rendering a draft as if it were a shop window.
+ */
+export function isPubliclyVisible(status: ListingLifecycleStatus): boolean {
+  return LIFECYCLE[status].publiclyVisible;
+}
+
+/** The owner-facing note about the moderation axis, when there is one. */
+export interface ModerationNotice {
+  readonly moderationStatus: ListingModerationStatus;
+  readonly messageKey: string;
+  readonly tone: ListingStatusTone;
+  /**
+   * Is the listing live WHILE this verdict is pending? True only for the
+   * re-moderation row — a published listing whose edit is being screened.
+   * The sentence differs from a first submission's precisely here.
+   */
+  readonly liveDuringReview: boolean;
+}
+
+/**
+ * What to say about the moderation axis, given BOTH fields.
+ *
+ * `undefined` means "nothing to add": an approved listing needs no note, and
+ * neither does a draft nobody has submitted. Every other combination has a
+ * sentence, including the ones that look contradictory — those are the ones
+ * worth naming.
+ */
+export function moderationNotice(
+  status: ListingLifecycleStatus,
+  moderationStatus: ListingModerationStatus
+): ModerationNotice | undefined {
+  const live = status === "published";
+
+  if (moderationStatus === "approved") {
+    // A takedown keeps `approved` on the moderation axis in some flows (the
+    // lifecycle moved, the verdict did not), so an approved BLOCKED listing
+    // still owes its owner an explanation — and it is the lifecycle's.
+    return undefined;
+  }
+
+  if (moderationStatus === "pending") {
+    if (live) {
+      return {
+        moderationStatus,
+        messageKey: LISTINGS_I18N_KEYS.moderationLiveEditPending,
+        tone: "waiting",
+        liveDuringReview: true,
+      };
+    }
+    if (status === "pending") {
+      return {
+        moderationStatus,
+        messageKey: LISTINGS_I18N_KEYS.moderationFirstReview,
+        tone: "waiting",
+        liveDuringReview: false,
+      };
+    }
+    // A draft/archived/sold row carrying a pending verdict: the submission
+    // was overtaken by a lifecycle move. Say that, rather than promising a
+    // review that will not put it back on the shelf.
+    return {
+      moderationStatus,
+      messageKey: LISTINGS_I18N_KEYS.moderationPendingOffline,
+      tone: "neutral",
+      liveDuringReview: false,
+    };
+  }
+
+  if (moderationStatus === "needs_review") {
+    return {
+      moderationStatus,
+      messageKey: live
+        ? LISTINGS_I18N_KEYS.moderationLiveNeedsReview
+        : LISTINGS_I18N_KEYS.moderationNeedsReview,
+      tone: "waiting",
+      liveDuringReview: live,
+    };
+  }
+
+  // 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,
+  };
+}
+
+/** Both halves at once — what a dashboard row and a detail header render. */
+export interface ListingStatusView {
+  readonly lifecycle: LifecycleCaption;
+  readonly moderation: ModerationNotice | undefined;
+  /** True when the two axes disagree in the way 0.5.0 made possible: live to
+   * the public, under review for its owner. The one combination a host is
+   * most likely to get wrong, so it is a named boolean and not an inference
+   * a caller repeats. */
+  readonly liveUnderReview: boolean;
+  /** What the owner can do next, in lifecycle terms — see
+   * {@link LISTING_TRANSITIONS}. */
+  readonly allowedTransitions: readonly ListingLifecycleStatus[];
+}
+
+export function listingStatusView(
+  status: ListingLifecycleStatus,
+  moderationStatus: ListingModerationStatus
+): ListingStatusView {
+  const moderation = moderationNotice(status, moderationStatus);
+  return {
+    lifecycle: lifecycleCaption(status),
+    moderation,
+    liveUnderReview: moderation?.liveDuringReview === true,
+    allowedTransitions: LISTING_TRANSITIONS[status],
+  };
+}
+
+/**
+ * The dashboard tabs, and the statuses each one folds together.
+ *
+ * The grouping is the SERVER's (`views.my_counters`), copied here so a tab's
+ * caption and its count cannot describe different sets: `active` includes
+ * PENDING beside PUBLISHED, and `drafts` includes REJECTED beside DRAFT —
+ * both because a listing in those states is something the owner is still
+ * working on. A client that grouped them its own way would show "3 active"
+ * over two rows.
+ */
+export const MY_LISTINGS_TABS = ["active", "drafts", "archived"] as const;
+
+export type MyListingsTab = (typeof MY_LISTINGS_TABS)[number];
+
+export const MY_LISTINGS_TAB_STATUSES: Readonly<
+  Record<MyListingsTab, readonly ListingLifecycleStatus[]>
+> = {
+  active: ["published", "pending"],
+  drafts: ["draft", "rejected"],
+  archived: ["archived", "paused", "expired", "sold"],
+};
+
+/** Which tab a listing belongs to, or `undefined` for BLOCKED — the one
+ * status `my/counters` counts in no tab at all. A dashboard that silently
+ * dropped it would hide exactly the listing whose owner most needs to know. */
+export function tabOf(
+  status: ListingLifecycleStatus
+): MyListingsTab | undefined {
+  for (const tab of MY_LISTINGS_TABS) {
+    if (MY_LISTINGS_TAB_STATUSES[tab].includes(status)) return tab;
+  }
+  return undefined;
+}

package/src/model/transitions.ts

@@ -0,0 +1,62 @@
+/**
+ * The lifecycle whitelist, mirrored from `stapel_listings.models
+ * .LISTING_TRANSITIONS`.
+ *
+ * ── A mirror, not a verdict ────────────────────────────────────────────────
+ *
+ * The server decides. `transition_to` raises `TransitionError` and the view
+ * answers **409 `error.409.invalid_listing_transition`** with
+ * `params.from_status`, and that refusal is rendered as the named sentence it
+ * is. What the mirror buys is the difference between a button that is there
+ * and does nothing and a button that is switched off WITH its reason: "you
+ * cannot mark a draft sold — publish it first" beats a 409 toast after the
+ * click, and beats a hidden control (which teaches nothing) by the whole
+ * private-space canon §6.3.
+ *
+ * The mirror is deliberately CONSERVATIVE in one direction only: it may never
+ * block something the server would allow. That is why it is a copy of the
+ * table rather than a hand-written summary of it, and why `test/status.test
+ * .ts` walks every source state.
+ *
+ * Two entries look odd and are correct:
+ *  - `published → blocked` exists, but the owner API has no route to it: only
+ *    `apply_moderation("rejected")` walks it. It is in the table because the
+ *    table is the model's, and leaving it out would make the mirror a
+ *    paraphrase.
+ *  - `blocked → published` is reinstatement after a successful appeal, also
+ *    moderation-driven. `archive` and `complete` are the only two transitions
+ *    this pair's API can actually request.
+ */
+import type { ListingLifecycleStatus } from "../api/types.js";
+
+export const LISTING_TRANSITIONS: Readonly<
+  Record<ListingLifecycleStatus, readonly ListingLifecycleStatus[]>
+> = {
+  draft: ["pending", "archived"],
+  pending: ["published", "rejected", "draft", "archived"],
+  published: ["paused", "expired", "sold", "blocked", "archived"],
+  blocked: ["published", "draft", "archived"],
+  paused: ["published", "archived", "expired"],
+  expired: ["pending", "published", "archived"],
+  sold: ["archived", "published"],
+  rejected: ["draft", "archived"],
+  archived: ["draft"],
+};
+
+/** Would the server accept this move? A same-status move is a no-op the
+ * server returns early on, so it counts as allowed. */
+export function canTransition(
+  from: ListingLifecycleStatus,
+  to: ListingLifecycleStatus
+): boolean {
+  return from === to || LISTING_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Deleting is not a transition and has its own rule
+ * (`views.destroy`): a PUBLISHED or PENDING listing is refused with
+ * `error.409.listing_cannot_delete_active` — archive it first.
+ */
+export function canDelete(status: ListingLifecycleStatus): boolean {
+  return status !== "published" && status !== "pending";
+}