@stapel/listings-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @stapel/listings-react

package/MODULE.md

@@ -0,0 +1,191 @@
+# @stapel/listings-react — module guide
+
+Pairs with **stapel-listings 0.6.1** (`>=0.6 <0.7`), 12 paths under
+`/listings/api/v1/`. Contract sources: the module's own
+`docs/{schema,errors,flows}.json`, pinned in `contract-pins.json` and
+regenerated under `pnpm gen:check`.
+
+## Layers
+
+```
+src/api/        listingsApi.ts   the 14 operations a storefront calls; the one home of path strings
+                types.ts         wire aliases + the one hand-mirrored shape (the stored DAO)
+                generated/       openapi-typescript, drift-gated
+src/model/      status.ts        the two axes → one caption, 9 × 4, asserted
+                transitions.ts   the server's whitelist, mirrored (UX only; the 409 is the verdict)
+                draft.ts         the *_draft twin ↔ the composer's values
+                features.ts      the stored DAO projection → what attributes-react formats
+                validation.ts    the mirror, and the split of the two publish 400s
+                mineSource.ts    THE GAP: no owner-scoped list endpoint exists
+                runtime · context · queryKeys · queries · mutations
+src/flows/      registry.ts      zero-flow shim (the module annotates no @flow_step)
+src/headless/   ListingsProvider · ListingDetail · ListingComposer · MyListings
+                Favorites · ListingActions · useMandateGate
+src/default/    the antd skin, `./default` subpath
+src/i18n/       keys · ru · es · errorsMap + generated/
+src/nav/        manifest.ts
+```
+
+Everything in `model/` except the hooks is pure — no React, no fetch — which
+is what lets the status table, the draft conversions and the mirror be tested
+without a DOM, and what lets an SSR render call them directly.
+
+## 1. Two axes, and the divergence 0.5.0 introduced
+
+`status` (nine states) is the lifecycle and the ONLY thing that decides public
+visibility: `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.
+
+```
+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
+```
+
+`model/status.ts` produces both halves of the sentence from BOTH fields, once.
+`test/status.test.ts` walks all 36 combinations, and names the four that look
+contradictory. `liveUnderReview` is a named boolean rather than an inference a
+caller repeats.
+
+The moderation axis is shown to the OWNER and to nobody else: a buyer has no
+use for "changes under review", and showing a stranger that a listing was
+refused would leak a verdict about someone else's content.
+
+## 2. Contract deltas — what the schema does not say
+
+### 2.1 The discriminator was broken in 0.6.0 and is fixed in 0.6.1
+
+0.6.0 declared `discriminator: {propertyName: "type", mapping: {"null":
+ConvertibleUnitDao}}` — one bogus entry instead of the ten type slugs — and
+openapi-typescript answers that by stripping `type` from every member and
+re-adding a synthetic discriminant, so the generated `IntDao` said
+`type: "IntDao"` where the wire sends `"int"`. `@stapel/categories-react` hit
+the same defect and routed around it through attributes-react's hand-mirrored
+types. **0.6.1 emits the ten slugs**, so this pair's `Schemas["FeatureDao"]`
+and `Schemas["FeatureDto"]` discriminate on the real values and ARE the wire
+types it uses; `ListingFeatureType` is derived from the union rather than
+hand-listed, so a type added upstream widens it automatically.
+
+What still comes from `@stapel/attributes-react` is the BEHAVIOUR — the value
+editors, the client mirror, the formatter — which is the spec's L0 seam and
+never was a workaround.
+
+### 2.2 A stored DAO carries `slug`; the schema's `FeatureDao` does not
+
+`features` / `features_title` / `features_badges` are
+`ListingFeaturesOutputField`, a plain `serializers.JSONField` whose OpenAPI
+*description* is swapped for the DAO union by an extension. A JSONField
+filters nothing: what reaches the wire is what `build_features_list` stored,
+and that is `{**dao, "slug": slug}` (`services/features.py`). The slug is
+load-bearing — it is how a card keys a badge and how a refusal finds its
+control — so `ListingFeatureDao` mirrors the runtime shape and says why.
+
+A row WITHOUT a slug is treated as malformed and counted
+(`unreadableFeatureCount`), never silently dropped: a synthesized index would
+key a badge to a position that moves whenever the category does.
+
+### 2.3 The DAO carries its type's config inline — and that is the good news
+
+`prefix`, `postfix`, `precision`, `trueLabel`, `maxSelected`, … all ride along
+beside `value`, which is why `<ListingCard>` can format "1200 W" from the row
+alone. A grid of forty cards costs one query and no category read. The one
+thing a DAO does not carry is `select`'s `options` table, so an option value
+falls back to its raw form — which is a translation KEY when the config is
+translatable (the default), so a host whose bundle carries the catalogue's
+copy still reads a word.
+
+### 2.4 The publish 400 has two shapes
+
+An invalid draft answers a BARE `ValidationBatchResult` (no
+`localizable_error`, no envelope), which core wraps as `stapel.http.400` with
+the batch on `StapelApiError.body`. A promotion that then fails
+(`REQUIRE_IMAGE_ON_PUBLISH` with no photo) answers the ordinary
+`error.400.publish_validation_failed`. `publishRefusal` branches on the BODY,
+not the status: a caller that branched on `status === 400` alone would put a
+sentence under a feature control.
+
+### 2.5 The description's refusal is already keyed like a control
+
+`services.publish.validate_draft` inserts `validate_description`'s row at the
+front of the same list, and that row's slug is literally `"description"`
+(`stapel_attributes/validation.py:726`) — the same key the mirror files its
+own length refusal under. One routing table covers both.
+
+## 3. Upstream asks
+
+| # | Ask | Why it matters here |
+|---|---|---|
+| 1 | An owner-scoped list (`?owner=me`, or a `my/listings` action) | Without it a seller cannot be shown their own drafts by any call the contract offers. Today: an injected `MyListingsSource`, and a named failure when there is none. `src/model/mineSource.ts`. |
+| 2 | A read that returns the `*_draft` twin | `GET /{pk}/` serializes the PUBLISHED fields only, so a draft abandoned and reopened later comes back empty. Editing a live listing is unaffected. |
+| 3 | `_get_own` in front of `update` / `partial_update` | Both are the plain `ModelViewSet` implementations under `IsAuthenticatedOrReadOnly` over `Listing.objects.all()`: **any authenticated caller can write any listing's draft fields through `PUT`/`PATCH`.** Every other owner operation checks ownership. This pair declines both and uses `save-draft`, which performs the same write with the check — so nothing is lost, but the endpoints remain reachable by anything else that speaks the contract. |
+| 4 | A `published()` filter (or an owner check) on `retrieve` | The detail endpoint answers 200 for a draft, a rejected and a blocked listing to anyone holding the id. The pair reports `publiclyVisible` from `status` and says which situation the reader is in, but it cannot stop the read. |
+| 5 | A public read-by-reference for stored images | `Listing.images` is opaque `<type>/<hash>` and nothing in this fleet resolves a stranger's reference (stapel-cdn's `file/exists/` is owner-scoped). Today: a host-supplied `resolveImage`. |
+| 6 | `slug` declared on `FeatureDao` | See §2.2 — it is on the wire and absent from the schema. |
+
+## 4. The three seams, and why none of them is an import
+
+`@stapel/cdn-react` and `@stapel/categories-react` are L2 pairs, and L2 pairs
+never import each other (the monorepo README states the direction). So:
+
+- **the gallery** is a structural `ListingImagesBag` — two members, satisfied
+  by `useUploadQueue()`'s bag. `bag.refs` IS the value of `images_draft` (same
+  order, first tile the cover) and `bag.settled` is the submit gate. That pair
+  wrote its bag to this contract on purpose (its §13.6 note 9);
+- **the category schema** is a plain `readonly FeatureDef[]`, plus a
+  `categorySlot` for the chooser;
+- **a stored image reference** is resolved by a host-supplied
+  `ListingImageResolver`.
+
+`@stapel/attributes-react` IS a dependency; it is L0, like `@stapel/image`.
+
+## 5. Gates and their reasons
+
+Every write in the pair is behind an `ActionAvailability`. The mandate axis is
+read through core's `MandateSource` seam — never derived here, because a
+storefront's derivation is "is there a session?" and a tenant app's is
+`@stapel/workspaces-react`'s. `matchMandate` has five required arms, so the
+two `unresolved` outcomes cannot fall into the refusal's branch: "we have not
+finished asking" and "we could not ask" are both distinct from "you may not".
+
+The lifecycle mirror (`model/transitions.ts`) is a COPY of
+`LISTING_TRANSITIONS`, not a summary of it, and it may never block what the
+server would allow. The 409 stays the verdict, rendered as the named refusal
+it is with `params.from_status` in the sentence.
+
+## 6. Locales
+
+`stapel-listings` ships no `translations/` directory, so 21 of the 63 registry
+codes have no upstream catalogue. They split by owner: 42 cross-cutting
+`stapel_core` codes are generated from core's catalogue, the 9
+`stapel_listings` codes are authored in `src/i18n/{ru,es}.ts` (nine lines to
+delete when upstream localizes), and the 12 `stapel_attributes` codes are
+deliberately left to `@stapel/attributes-react`. `test/i18n.test.ts` asserts
+over the UNION of the two bundles a host actually registers, so nobody can
+make it pass by copying the other package's keys in.
+
+## 7. Tests
+
+142 in 8 files (138 under `test`, 4 under `test:pack`). The ones that carry
+the weight:
+
+- `status.test.ts` — the 9 × 4 table, the tab grouping (including BLOCKED,
+  which `my_counters` counts in no tab at all), and the transition mirror;
+- `draft.test.ts` — the payload, in both directions: type tagging from the
+  category schema, blanks omitted rather than nulled, the countable/stock
+  cross-field rule, code-point length, the two kinds of publish 400;
+- `compose.test.tsx` — the submission against the wire: the row is created
+  with the category and nothing else, the gallery's refs go out in order, the
+  save happens BEFORE the publish, a `ValidationBatchResult` lands on the
+  control that caused it, and the two publish outcomes are told apart by what
+  the server answered;
+- `detail.test.tsx` — four absences and four sentences, the owner-only
+  moderation axis, and the favourite control blocked-but-visible for a
+  visitor;
+- `mine.test.tsx` — the named gap, real counters beside it, and no badge at
+  all for a count that failed to load.

package/README.md

@@ -0,0 +1,169 @@
+# @stapel/listings-react
+
+The frontend pair for **stapel-listings**: the listing page, the submission
+flow, and the seller's dashboard.
+
+Two facts about this module shape the whole package, and both are easy to get
+subtly wrong:
+
+1. **A listing has two independent state axes.** `status` decides whether
+   anyone can see it; `moderation_status` decides nothing about that. Since
+   stapel-listings 0.5.0 an edit to a LIVE listing keeps `status: published`
+   and moves only the moderation axis — so "published, and we are reviewing
+   your changes" is a real state, and a screen that computed either field from
+   the other would either hide a listing buyers are reading or never tell its
+   owner their edit is being screened.
+2. **A publish refusal is per-field, and it arrives in an unusual envelope.**
+   `POST /{pk}/publish/` answers an invalid draft with a bare
+   `ValidationBatchResult` — no `localizable_error` — while a promotion that
+   fails afterwards answers the ordinary one. Two 400s, two meanings.
+
+Business + state in the main entry, zero visual opinion; the antd skin lives
+behind `./default`. Built on `@stapel/core` (typed client + `StapelApiError`
+envelope, `LoadState`, `ActionAvailability`, the mandate seam, i18n engine,
+TanStack Query), `@stapel/attributes-react` (the value editors, the client
+mirror and the display formatter) and `@stapel/image` (the variant ladder).
+
+## Install
+
+```
+pnpm add @stapel/listings-react @stapel/core @stapel/attributes-react @stapel/image @tanstack/react-query react
+# for the default skin:
+pnpm add antd @stapel/tokens-antd
+```
+
+## A listing page, in six lines
+
+```tsx
+import { createListingsRuntime, ListingsProvider } from "@stapel/listings-react";
+import { ListingDetailPane } from "@stapel/listings-react/default";
+
+const runtime = createListingsRuntime({
+  baseUrl: "/listings/api/v1/",
+  resolveImage: (ref) => myCdn.describe(ref), // see "Photos" below
+});
+
+export function ListingRoute({ id }: { id: number }) {
+  return (
+    <ListingsProvider runtime={runtime}>
+      <ListingDetailPane id={id} />
+    </ListingsProvider>
+  );
+}
+```
+
+## The card is a slot, not an import
+
+A marketplace's result grid goes through `@stapel/search-react`, because
+`promoted` (DSA Art. 26) rides every search item under every sort and a card
+list that carried the marking on some pages and not others would be worse than
+one that never claimed it. The two pairs never import each other — the
+container is the seam:
+
+```tsx
+<SearchPage renderCard={(item) => <ListingCard listing={item.card} href={`/l/${item.id}`} />} />
+```
+
+`<ListingCard>` renders its badges from `features_badges`, a stored projection
+that carries each type's display config beside its value. A grid of forty
+cards therefore costs one query and **no category read**.
+
+## Submitting a listing
+
+Four contracts meet on the composer, and three of them arrive as seams rather
+than dependencies:
+
+| what | how it arrives | why |
+|---|---|---|
+| the category's schema | `features: FeatureDef[]` | `@stapel/categories-react` is an L2 pair; L2 pairs do not import each other |
+| the photos | `images` — two members of `@stapel/cdn-react`'s upload bag | same rule; `bag.refs` IS `images_draft` and `bag.settled` is the submit gate |
+| the value editors | `@stapel/attributes-react` | L0, so a direct dependency |
+
+```tsx
+const gallery = useUploadQueue({ max: 10 });        // @stapel/cdn-react
+const features = useCategoryFeatures(categoryId);   // @stapel/categories-react
+
+<ListingComposerPage
+  features={features}
+  images={gallery}
+  categorySlot={<CategoryPickerField value={categoryId} onChange={setCategoryId} />}
+  gallerySlot={<MediaGalleryField bag={gallery} />}
+/>
+```
+
+The flow is `create draft → save into it → publish`. The composer always saves
+before it publishes, because `publish` promotes the STORED draft: publishing
+without saving would promote whatever was there before the last keystroke.
+
+### Every switched-off publish button says which of six reasons it is
+
+sign in · choose a category · we could not load what this category asks for ·
+this build cannot draw one of these details · wait for the photos · fix the
+highlighted fields. They are ordered the way a person would be told, and the
+reason is rendered beside the button.
+
+## Photos need a resolver, and the pair says so
+
+`Listing.images` is a list of opaque CDN references (`<type>/<hash>`), and
+**no contract in this fleet resolves a stranger's reference**: there is no
+public read-by-reference in stapel-listings, and stapel-cdn's `file/exists/`
+is owner-scoped. So the runtime takes a `resolveImage` from the deployment,
+which knows where its CDN serves from, and a pane without one says "photos
+cannot be shown here" instead of drawing a broken `<img>`. Inventing
+`${cdnBase}/${ref}` would be writing a contract nobody agreed to.
+
+## What this pair cannot do, and why
+
+**List your own listings.** stapel-listings 0.6.1 has no owner-scoped list
+endpoint: `GET /listings/` answers `published()` and takes no owner parameter.
+The counters (`my/counters`) are real and are shown; the rows come from an
+injected `MyListingsSource`, and with none the dashboard reports a NAMED
+failure rather than an empty grid — "we cannot ask" and "you have no listings"
+are different sentences. See `src/model/mineSource.ts` for the upstream asks.
+
+**Reopen an abandoned draft.** No read returns the `*_draft` twin:
+`GET /{pk}/` serializes the published fields. Editing a LIVE listing works
+completely (the published half IS the listing); a draft reopened in a later
+session comes back empty and the composer says so.
+
+**Write through `PUT` / `PATCH`.** They are on the contract and absent from
+`ListingsApi`. Every other owner operation routes through `views._get_own`;
+these two are the plain `ModelViewSet` implementations under
+`IsAuthenticatedOrReadOnly` over `Listing.objects.all()`, so any authenticated
+caller can write any listing's draft fields through them.
+`POST /{pk}/save-draft/` performs the same write WITH the ownership check, so
+the pair uses that and nothing is lost.
+
+## Layers
+
+```
+src/api/       listingsApi.ts · types.ts · generated/schema.ts
+src/model/     status · transitions · draft · features · validation · mineSource
+               runtime · context · queryKeys · queries · mutations
+src/flows/     registry.ts (zero-flow shim — the module annotates none)
+src/headless/  ListingsProvider · ListingDetail · ListingComposer · MyListings
+               Favorites · ListingActions · useMandateGate
+src/default/   the antd skin, `./default` subpath
+src/i18n/      keys · ru · es · errorsMap + generated/
+src/nav/       manifest.ts
+```
+
+`model/` is pure apart from the hooks: the status table, the draft
+conversions, the mirror and the publish-400 split are all plain functions, so
+the parts worth getting right are tested without a DOM.
+
+## Locales
+
+English is inline. `./i18n/ru` and `./i18n/es` are opt-in subpaths and carry
+the UI copy as well as the nine `stapel_listings` error keys — the storefront
+is ru-first (owner verdict F1), and a half-translated submission form is
+visible immediately. The twelve `stapel_attributes` keys are deliberately NOT
+here: `@stapel/attributes-react` owns and translates them, and one refusal must
+not have two sentences.
+
+## Documentation
+
+- `MODULE.md` — the module guide: the two axes in full, the contract deltas,
+  the upstream asks.
+- `manifest.json` / `llms.txt` — generated self-description, drift-gated.
+- `nav-manifest.json` — the four routes this pair contributes.