@stapel/listings-react 0.26.0 → 0.28.0

package/src/model/draft.ts

@@ -224,6 +224,28 @@ function toWireFeatures(
   return toFeaturesDto(features, values) as unknown as WireFeaturesDraft;
 }
 
+/** One field of the `save-draft` body, by the name the wire uses. */
+export type ListingDraftField = keyof ListingDraftPatch;
+
+/** Options for {@link draftPatchFromValues}. */
+export interface DraftPatchOptions {
+  /**
+   * NAME THE FIELDS THIS SAVE IS WRITING, and the body carries no others.
+   *
+   * `save-draft` REPLACES every field in the body — it does not merge — so a
+   * body is not "the values I have", it is "the fields I am claiming". A save
+   * fired by one control (a photo settling, a blurred title) previously
+   * claimed all fourteen, which is only harmless while every one of them is
+   * loaded and true.
+   *
+   * Given, only these keys are spelled; the omission rules below still apply
+   * inside the selection, so naming `features_draft` without a schema still
+   * writes nothing. Absent, the whole body is sent, which is right for the
+   * composer's own save — it holds every value on the form.
+   */
+  readonly fields?: readonly ListingDraftField[];
+}
+
 /**
  * The composer's values → the `save-draft` body.
  *
@@ -234,12 +256,34 @@ function toWireFeatures(
  * (`error.400.listing_feature_not_allowed`), which is why
  * {@link retainKnownFeatureValues} prunes on the way in rather than letting
  * the server explain it.
+ *
+ * ── NO SCHEMA IS NOT AN EMPTY ANSWER SHEET ───────────────────────────────
+ *
+ * An absent or empty `features` used to produce `features_draft: {}`, and
+ * `save-draft` REPLACES that map rather than merging into it — so a save that
+ * left before the category's schema arrived DELETED every characteristic the
+ * row was holding, while the form on screen still showed them. Measured by a
+ * live container over two cold loads of one draft: a reopen's own
+ * settled-photo save fires in the first commit, before the row's category has
+ * even been adopted, and the row alternated between the draft's answers and
+ * none of them (a client storefront's README, "Named gaps").
+ *
+ * `{}` is a claim — "this listing has no characteristics" — and a caller with
+ * no schema is in no position to make it. So the key is OMITTED entirely
+ * whenever there is no schema to tag values with, and `save-draft` then
+ * leaves the stored map exactly as it was. A category that genuinely declares
+ * no features writes nothing either, which is the same answer arrived at
+ * honestly: there is nothing to say and the row already says it.
+ *
+ * {@link DraftPatchOptions.fields} is the general form of the same rule — a
+ * save that names what it is writing cannot erase what it is not.
  */
 export function draftPatchFromValues(
   values: ListingDraftValues,
-  features: readonly FeatureDef[]
+  features: readonly FeatureDef[] | undefined,
+  options: DraftPatchOptions = {}
 ): ListingDraftPatch {
-  return {
+  const full: ListingDraftPatch = {
     // Omitted while unchosen rather than sent as `""`: a draft is allowed to
     // have no category (0.21.4), and `""` is not "no category" on the wire —
     // it is an empty id the serializer refuses. The category is written by
@@ -258,7 +302,11 @@ export function draftPatchFromValues(
     // sent here is discarded. Sending one would be a claim the wire ignores.
     lat_draft: values.location.lat,
     lon_draft: values.location.lon,
-    features_draft: toWireFeatures(features, values.features),
+    // Omitted, not emptied, when there is no schema to tag with — see the
+    // doc above. `{}` is a claim about the listing; silence is not.
+    ...(features !== undefined && features.length > 0
+      ? { features_draft: toWireFeatures(features, values.features) }
+      : {}),
     countable: values.countable,
     // The pair mirrors the model's cross-field rule rather than sending a
     // contradiction: a service carries no quantity, and `validate_countable
@@ -266,6 +314,16 @@ export function draftPatchFromValues(
     stock_quantity: values.countable ? values.stockQuantity : null,
     auto_republish: values.autoRepublish,
   };
+  const named = options.fields;
+  if (named === undefined) return full;
+  // A selection, not a second body: the field's VALUE is still whatever the
+  // rules above produced, so a named field the rules omit stays omitted.
+  const wanted = new Set<string>(named);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(full)) {
+    if (wanted.has(key)) out[key] = value;
+  }
+  return out as ListingDraftPatch;
 }
 
 /**

package/src/model/status.ts

@@ -285,8 +285,8 @@ export function listingStatusView(
 }
 
 /**
- * The three tabs `my/counters` COUNTS, and the statuses each one folds
- * together.
+ * The three tabs whose ROWS come off a keyset page, 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
@@ -294,10 +294,17 @@ export function listingStatusView(
  * 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.
+ *
+ * The name is about the SOURCE, not about the counter: `MyCountersResponse`
+ * carries four integers since stapel-listings 0.22.4 (`blocked` joined the
+ * three), and this is still the set a {@link MyListingsCountedTab} —
+ * `MyListingsSource`'s whole parameter type — may name. The removed tab reads
+ * its rows off `?status=blocked` directly and unpaged, so a host that
+ * implemented the seam before the fourth tab existed is never handed it.
  */
 export const MY_LISTINGS_COUNTED_TABS = ["active", "drafts", "archived"] as const;
 
-/** One of the three tabs `MyCountersResponse` carries a number for. */
+/** One of the three tabs a `MyListingsSource` is asked for. */
 export type MyListingsCountedTab = (typeof MY_LISTINGS_COUNTED_TABS)[number];
 
 const COUNTED_TAB_STATUSES: Readonly<
@@ -308,8 +315,9 @@ const COUNTED_TAB_STATUSES: Readonly<
   archived: ["archived", "paused", "expired", "sold"],
 };
 
-/** Which of the three COUNTED tabs a status belongs to, or `undefined` for
- * one the server's own counter groups nowhere — `blocked`, today. */
+/** Which of the three keyset-paged tabs a status belongs to, or `undefined`
+ * for one none of them folds in — `blocked`, today, which has a tab and a
+ * counter of its own and a different row source under it. */
 export function countedTabOf(
   status: ListingLifecycleStatus
 ): MyListingsCountedTab | undefined {
@@ -320,13 +328,16 @@ export function countedTabOf(
 }
 
 /**
- * The statuses the server's own counter groups nowhere — `blocked`, and
- * nothing else today.
+ * The statuses none of the three paged tabs folds in — `blocked`, and nothing
+ * else today.
  *
  * DERIVED, not written down a second time: a status added upstream and left
- * out of the counter groupings lands here automatically and gets shown, which
- * is the opposite of what a hardcoded `["blocked"]` would do the day it goes
- * stale.
+ * out of the tab groupings lands here automatically and gets shown, which is
+ * the opposite of what a hardcoded `["blocked"]` would do the day it goes
+ * stale. That the server now has a `blocked` COUNTER for the same set does not
+ * make the derivation redundant: the counter names one status and this names
+ * whatever the three groupings leave over, which is the set the fourth tab
+ * must ASK for.
  */
 export const MY_LISTINGS_UNTABBED_STATUSES: readonly ListingLifecycleStatus[] =
   LISTING_STATUSES.filter((status) => countedTabOf(status) === undefined);
@@ -350,12 +361,16 @@ export const MY_LISTINGS_UNTABBED_STATUSES: readonly ListingLifecycleStatus[] =
  * ── Why a fourth tab and not the archive ─────────────────────────────────
  *
  * Folding `blocked` into `archived` is the other shape this could take, and
- * it costs the count: `my/counters` has three integers and no fourth, so an
- * archive tab holding takedowns would read the server's `archived` number —
- * `0` — until the tab was opened and its rows could raise it. The fourth tab
- * is counted from its OWN read (`?status=blocked`, unpaged), so the number is
- * right while the seller is looking at a different tab, which is exactly the
- * moment D407 was measured at.
+ * it cost the count: when D407 was written `my/counters` had three integers
+ * and no fourth, so an archive tab holding takedowns would have read the
+ * server's `archived` number — `0` — until the tab was opened and its rows
+ * could raise it. The fourth tab was counted from its OWN read
+ * (`?status=blocked`, unpaged) so that the number was right while the seller
+ * was looking at a different tab, which is exactly the moment D407 was
+ * measured at. stapel-listings 0.22.4 puts `blocked` in the counter, so the
+ * number is the server's now and that read is only the tab's rows — but the
+ * property it was there to defend is the same one, and it is now defended by
+ * the wire instead of by a page.
  *
  * The archive keeps its meaning too, which is not nothing: "I put this away"
  * and "a moderator took this down" are not the same sentence and a tab that