@stapel/listings-react 0.10.0 → 0.12.0

package/src/model/features.ts

@@ -22,63 +22,268 @@
  * `order`, `title`, `badge`) are simply ignored by every formatter. Copying a
  * hand-picked subset instead would be a list to keep in step with ten types.
  *
- * ── What a DAO does NOT carry, and the one line that repairs it ────────────
+ * ── What a DAO does NOT carry, and the tables that repair it ───────────────
  *
  * `select`'s `options`. `SelectType.dto_to_dao` stores the chosen VALUES and
  * the ui config, never the option table — the table lives on the CATEGORY, and
  * not needing it is the whole point of the projection.
  *
- * The consequence was a defect the visual pass caught on every card and every
- * spec row: `formatFeatureValue` resolves an option's copy by looking the
- * value up in `config.options`, and with no table it falls through to
- * `String(value)`. The stored value of a translatable catalogue IS a
- * translation key, so a listing page printed `demo.condition.used` and
- * `demo.brand.bosch` at people. (The server does not have this problem: its
- * own `format_value` has the category's config in hand.)
- *
- * So the split below synthesizes the IDENTITY table — `{value: v, label: v}`
- * for each stored value — which is exactly the table a translatable catalogue
- * would have produced, since its labels ARE the keys. `formatFeatureValue`
- * then runs the value through the host's `t` and a bundle carrying the
- * catalogue copy reads "Used". A bundle that does not still shows the key, on
- * purpose: a visible `option.condition.used` gets fixed, an invented "Used"
- * ships wrong. A NON-translatable catalogue stores literal labels, `t` returns
- * an unknown key unchanged, and the output is what it always was.
+ * `formatFeatureValue` resolves an option's copy by looking the value up in
+ * `config.options`, so with no table at all it falls through to
+ * `String(value)` and the STORAGE SLUG reaches the screen: a live classified
+ * deployment printed "Condition: b-u" on its spec rows and a three-slug
+ * subtitle on its cards. (The server never had this problem: its own
+ * `format_value` has the category's config in hand.)
+ *
+ * So the split below rebuilds the table, from the best of three sources:
+ *
+ *  1. The LABEL SNAPSHOT. A `select` DAO written by a stapel-attributes that
+ *     snapshots labels carries `labels`, a `string[]` positionally aligned
+ *     with `value` — the same device `ref_select` has always used for its
+ *     vocabulary terms, and the reason a published listing keeps printing the
+ *     copy it was published with however the category is edited afterwards.
+ *  2. The CATEGORY's own option table, when the display surface has it —
+ *     `GET /categories/api/v1/categories/{id}/features/` answers with
+ *     `{"slug":"condition","config":{"type":"select","options":[…]}}`, labels
+ *     and all. It is handed in through {@link FeatureCopySource}, because a
+ *     library may not fetch another module's endpoint and a card grid has no
+ *     category to fetch one FOR.
+ *  3. The IDENTITY table — `{value: v, label: v}` — for a value neither of the
+ *     first two names. That is exactly the table a TRANSLATABLE catalogue
+ *     would have produced, since its labels ARE its keys, so such a value
+ *     still reads out of the host's bundle; a NON-translatable one keeps
+ *     showing the slug. A visible `b-u` gets fixed by rung 1 or 2, and an
+ *     invented "Used" ships wrong, so the floor stays the value itself.
+ *
+ * ── Which rung wins, and why that order and not the other one ──────────────
+ *
+ * The SNAPSHOT outranks the category. The snapshot is what the listing was
+ * PUBLISHED with; the category is what the catalogue says today. A category
+ * whose option copy was rewritten after a listing went live must not silently
+ * restate that listing — the person reading it is reading an advert somebody
+ * else wrote, not a form. The category outranks identity, which is the whole
+ * point: every listing published before the snapshot release, and every row
+ * written by an older server, has no snapshot to outrank it and prints its
+ * slug today.
+ *
+ * A category def that does not describe the STORED row — a different value
+ * type, or no such slug — is ignored rather than forced. A category edited
+ * from `select` to `string` is a different question, and pairing its options
+ * against this row's values would print one question's copy under another
+ * question's answer, which does not even LOOK wrong.
+ *
+ * With no category defs supplied, every rung above 1 is absent and the
+ * projection behaves exactly as it did.
+ *
+ * ── The category path is the REPAIR path, not the mechanism ────────────────
+ *
+ * The primary mechanism is the server's, and it is the snapshot: stapel-
+ * attributes writes `labels` beside a `select`'s codes exactly as it always
+ * has for `ref_select`, and stapel-listings ships a reprojection command that
+ * back-fills rows written before it. Nothing here competes with that. Rung 2
+ * exists for the three states that outlive that deploy:
+ *
+ *   - a row written before the snapshot existed and not yet reprojected;
+ *   - a deployment that never runs the reprojection;
+ *   - a category whose option copy was edited AFTER publication — where the
+ *     snapshot is deliberately the older and correct answer, which is exactly
+ *     why the precedence runs the way it does above.
+ *
+ * The resulting table is then read the one way `formatFeatureValue` reads any
+ * option table — literal when the config says `translatable_options: false`,
+ * through the host's `t` otherwise, where a translatable catalogue's label IS
+ * the key and an unknown key comes back unchanged. The flag stays the ROW's:
+ * it describes how the listing's own stored config wants its copy resolved,
+ * and an unknown key resolves to itself either way.
  */
 import type { FeatureDef, FeatureValueDto } from "@stapel/attributes-react";
+import { featureType } from "@stapel/attributes-react";
 import type { ListingFeatureDao, ListingFeatureView } from "../api/types.js";
 
-/** Keys that belong to the DAO envelope rather than to the type's config. */
+/**
+ * Keys that belong to the DAO envelope rather than to the type's config.
+ *
+ * `labels` is deliberately NOT one of them, even though this module now reads
+ * it: `ref_select` and `ref_hierarchical_select` resolve their vocabulary
+ * terms from `config.labels` (attributes-react's `refLabels` reads the value
+ * envelope first and the config second, and this split hands the formatter a
+ * bare `{type, value}`), so envelope-ing the key would blank every term those
+ * two types print. For `select` the key is simply inert — its formatter reads
+ * `options` and nothing else — so carrying it costs a reference.
+ */
 const ENVELOPE = new Set(["slug", "value", "name", "order", "title", "badge"]);
 
-/** The two types whose stored `value` is an option key rather than the thing
- * itself. `hierarchical_select` is deliberately absent: its formatter joins
- * the path with " / " and never consults an option table at all. */
+/** The type whose stored `value` is a flat list of option keys rather than the
+ * things themselves, and whose copy therefore has to be repaired pairwise.
+ * `ref_select` is absent because it repairs itself: its `labels` snapshot has
+ * always been mandatory (no display package can reach a vocabulary term). */
 const OPTION_VALUED = new Set(["select"]);
 
+/**
+ * The type whose copy lives in a TREE on the category rather than in a flat
+ * table: `hierarchical_select` stores a path of option keys and
+ * `formatFeatureValue` walks `config.options` level by level to name each
+ * step, so a row without that tree prints "passenger / sedan" — the storage
+ * keys — exactly as a table-less `select` prints `b-u`.
+ *
+ * It is kept apart from {@link OPTION_VALUED} because the two repairs are not
+ * the same repair: a flat positional `labels` list cannot describe a tree, so
+ * there is nothing to merge and the category's tree is adopted whole or not at
+ * all. `formatFeatureValue` already keeps a step the tree does not contain as
+ * its raw value, so an adopted tree can only add copy, never blank one out.
+ */
+const TREE_VALUED = new Set(["hierarchical_select"]);
+
 /** The canon's `FeatureDef.translate` vocabulary — three values, closed. */
 function isTranslateMode(value: unknown): value is "all" | "title" | "none" {
   return value === "all" || value === "title" || value === "none";
 }
 
 /**
- * The identity option table for a stored `select` — see the module header.
+ * The category's feature defs, for a display surface that has them.
+ *
+ * A detail page reads one listing of one category and its container usually
+ * holds that category's schema already (it is the same read the composer is
+ * given); a card grid spanning forty categories does not, and passes nothing.
+ * Optional for exactly that reason: the seam adds a source of copy, it never
+ * becomes a requirement, and a host that wires nothing keeps the behaviour it
+ * has.
+ */
+export interface FeatureCopySource {
+  /**
+   * The chosen category's features, as
+   * `GET /categories/api/v1/categories/{id}/features/` answers — the same
+   * `readonly FeatureDef[]` `<ListingComposerPage>` already takes. Defs are
+   * matched to stored rows by slug AND value type; anything else is ignored.
+   */
+  readonly categoryFeatures?: readonly FeatureDef[];
+}
+
+/** Category defs keyed by slug, or `undefined` when there are none to key —
+ * built once per list so a 40-row projection is not 40 linear scans. */
+type CategoryDefs = ReadonlyMap<string, FeatureDef>;
+
+function categoryDefs(source: FeatureCopySource): CategoryDefs | undefined {
+  const defs = source.categoryFeatures;
+  if (defs === undefined || defs.length === 0) return undefined;
+  const index = new Map<string, FeatureDef>();
+  for (const def of defs) {
+    // First wins: a duplicate slug in a category is a catalogue defect, and
+    // silently preferring the last one would make the copy depend on the
+    // order the endpoint happened to serialize.
+    if (typeof def.slug === "string" && def.slug.length > 0 && !index.has(def.slug)) {
+      index.set(def.slug, def);
+    }
+  }
+  return index.size === 0 ? undefined : index;
+}
+
+/**
+ * The category's definition OF THIS ROW, or `undefined`.
+ *
+ * Same slug and same value type, or it is not a definition of this row — see
+ * the module header on why a mismatch is ignored rather than forced.
+ */
+function categoryDefFor(
+  dao: ListingFeatureDao,
+  defs: CategoryDefs | undefined
+): FeatureDef | undefined {
+  if (defs === undefined) return undefined;
+  const def = defs.get(dao.slug);
+  if (def === undefined) return undefined;
+  return featureType(def) === dao.type ? def : undefined;
+}
+
+/** A category def's declared option list, when it declares one. */
+function declaredOptions(def: FeatureDef | undefined): readonly unknown[] | undefined {
+  const raw = def?.config?.["options"];
+  return Array.isArray(raw) ? (raw as readonly unknown[]) : undefined;
+}
+
+/** One entry of an option list → its `(value, label)` pair, when it is one. */
+function optionPair(entry: unknown): { value: string; label: string } | undefined {
+  if (entry === null || typeof entry !== "object") return undefined;
+  const option = entry as { value?: unknown; label?: unknown };
+  if (typeof option.value !== "string" || option.value.length === 0) return undefined;
+  return {
+    value: option.value,
+    label: typeof option.label === "string" && option.label.length > 0 ? option.label : option.value,
+  };
+}
+
+/**
+ * The option table a stored `select` needs and does not carry — see the
+ * module header. The category's table underneath, the row's own `labels`
+ * snapshot on top, the values themselves as the floor.
+ *
+ * The alignment rule is the engine's own (`labels if len(labels) ==
+ * len(codes) else codes`): a snapshot of a different length than `value` is a
+ * snapshot of some other value list, and pairing the two anyway would print
+ * one option's copy against another option's value — worse than a slug,
+ * because it does not LOOK wrong. So a length mismatch drops the whole
+ * snapshot rather than pairing the overlap, and the row falls back to the
+ * category (or to identity). Within a usable snapshot, a missing or empty
+ * entry falls back to whatever the category, then the value itself, offers for
+ * that one pair.
  *
  * Returns `undefined` when there is nothing to add (another type, a config
- * that already carries a table, a value that is not a list of strings), so the
- * common path allocates nothing and a DAO that DOES carry options is left
- * exactly as it arrived.
+ * that already carries a table, a value that is not a list of strings and no
+ * category table either), so the common path allocates nothing and a DAO that
+ * DOES carry options is left exactly as it arrived — a stored table is a
+ * write-time snapshot of the whole question, which is a stronger statement
+ * about this listing than either the per-value snapshot or today's category.
  */
-function synthesizedOptions(
+function selectOptions(
   dao: ListingFeatureDao,
-  config: Readonly<Record<string, unknown>>
+  config: Readonly<Record<string, unknown>>,
+  categoryDef: FeatureDef | undefined
 ): readonly { value: string; label: string }[] | undefined {
   if (typeof dao.type !== "string" || !OPTION_VALUED.has(dao.type)) return undefined;
   if (Array.isArray(config["options"])) return undefined;
-  const raw = Array.isArray(dao.value) ? dao.value : [dao.value];
-  const values = raw.filter((item): item is string => typeof item === "string");
-  if (values.length === 0) return undefined;
-  return values.map((value) => ({ value, label: value }));
+  const raw: readonly unknown[] = Array.isArray(dao.value)
+    ? (dao.value as readonly unknown[])
+    : [dao.value];
+  const snapshot: unknown = dao.labels;
+  const labels: readonly unknown[] | undefined =
+    Array.isArray(snapshot) && snapshot.length === raw.length
+      ? (snapshot as readonly unknown[])
+      : undefined;
+
+  // A Map so the three rungs can overwrite one another by value instead of
+  // the reader having to scan a list that carries the same value twice —
+  // `labelOf` takes the FIRST match, so a duplicate would make the losing
+  // rung win.
+  const table = new Map<string, string>();
+  for (const entry of declaredOptions(categoryDef) ?? []) {
+    const pair = optionPair(entry);
+    if (pair !== undefined) table.set(pair.value, pair.label);
+  }
+  raw.forEach((value, index) => {
+    if (typeof value !== "string") return;
+    const label = labels?.[index];
+    if (typeof label === "string" && label.length > 0) table.set(value, label);
+    else if (!table.has(value)) table.set(value, value);
+  });
+  if (table.size === 0) return undefined;
+  return [...table].map(([value, label]) => ({ value, label }));
+}
+
+/**
+ * The category's option TREE, adopted whole for a `hierarchical_select` that
+ * stored none — see {@link TREE_VALUED}.
+ *
+ * Nothing is merged and nothing is rewritten: the tree is the category's
+ * structure, and this projection has no per-level snapshot with which to
+ * disagree about it.
+ */
+function adoptedTree(
+  dao: ListingFeatureDao,
+  config: Readonly<Record<string, unknown>>,
+  categoryDef: FeatureDef | undefined
+): readonly unknown[] | undefined {
+  if (typeof dao.type !== "string" || !TREE_VALUED.has(dao.type)) return undefined;
+  if (Array.isArray(config["options"])) return undefined;
+  return declaredOptions(categoryDef);
 }
 
 /**
@@ -90,7 +295,16 @@ function synthesizedOptions(
  * position that changes whenever the category does.
  */
 export function featureFromDao(
-  dao: ListingFeatureDao
+  dao: ListingFeatureDao,
+  source: FeatureCopySource = {}
+): ListingFeatureView | undefined {
+  return featureView(dao, categoryDefs(source));
+}
+
+/** The work of {@link featureFromDao}, against an already-built index. */
+function featureView(
+  dao: ListingFeatureDao,
+  defs: CategoryDefs | undefined
 ): ListingFeatureView | undefined {
   if (typeof dao.slug !== "string" || dao.slug.length === 0) return undefined;
 
@@ -98,7 +312,9 @@ export function featureFromDao(
   for (const [key, value] of Object.entries(dao)) {
     if (!ENVELOPE.has(key)) config[key] = value;
   }
-  const options = synthesizedOptions(dao, config);
+  const categoryDef = categoryDefFor(dao, defs);
+  const options =
+    selectOptions(dao, config, categoryDef) ?? adoptedTree(dao, config, categoryDef);
   if (options !== undefined) config["options"] = options;
 
   const feature: FeatureDef = {
@@ -125,11 +341,13 @@ export function featureFromDao(
  * unreadableFeatureCount} so a skin can say how many rather than pretend the
  * listing had fewer attributes. */
 export function featuresFromDaoList(
-  daos: readonly ListingFeatureDao[] | null | undefined
+  daos: readonly ListingFeatureDao[] | null | undefined,
+  source: FeatureCopySource = {}
 ): readonly ListingFeatureView[] {
+  const defs = categoryDefs(source);
   const out: ListingFeatureView[] = [];
   for (const dao of daos ?? []) {
-    const view = featureFromDao(dao);
+    const view = featureView(dao, defs);
     if (view !== undefined) out.push(view);
   }
   return out;

package/src/model/validation.ts

@@ -93,6 +93,51 @@ export const TITLE_FIELD = "title";
 export const PRICE_FIELD = "price";
 export const IMAGES_FIELD = "images";
 export const CATEGORY_FIELD = "category_id";
+/** The coordinate pair, as one control: a latitude alone is not a place. */
+export const LOCATION_FIELD = "location";
+
+/**
+ * The composer's OWN controls, in the order the draft declares them.
+ *
+ * The mirror is a `Record`, and a record has no order worth trusting — its
+ * feature refusals happen to come first because of a spread. "Which field is
+ * the first unsatisfied one?" is a question a person asks about a FORM, so the
+ * answer is written down as a list rather than read off an object: the
+ * category (nothing else can be answered until it is chosen), then the
+ * listing's own fields, then — appended by the caller — the category's
+ * features in the order the schema declares them.
+ */
+export const LISTING_FIELD_ORDER: readonly string[] = [
+  CATEGORY_FIELD,
+  TITLE_FIELD,
+  DESCRIPTION_FIELD,
+  PRICE_FIELD,
+  LOCATION_FIELD,
+  IMAGES_FIELD,
+];
+
+/**
+ * The API's own field names → the control that holds them.
+ *
+ * The draft serializer writes `*_draft` columns, and the two coordinates are
+ * one field on screen. Without this table a per-field 400 has nowhere to land
+ * and becomes a banner nobody can act on — which is the whole of blocker C2's
+ * second half: a save refused for `lat_draft` painted "Validation error" over
+ * the footer while the location control, the only thing the person could have
+ * changed, stayed clean.
+ */
+const CONTROL_OF_API_FIELD: Readonly<Record<string, string>> = {
+  title_draft: TITLE_FIELD,
+  description_draft: DESCRIPTION_FIELD,
+  price_draft: PRICE_FIELD,
+  images_draft: IMAGES_FIELD,
+  category_id: CATEGORY_FIELD,
+  lat_draft: LOCATION_FIELD,
+  lon_draft: LOCATION_FIELD,
+  location_id_draft: LOCATION_FIELD,
+  location_label_draft: LOCATION_FIELD,
+  stock_quantity: "stockQuantity",
+};
 
 /** A client-side refusal. `status: 0` on purpose: a rule this build applied
  * must never be indistinguishable from one that came over the wire. */
@@ -162,7 +207,7 @@ export function mirrorListingFields(
   const hasLat = lat !== null && lat.length > 0;
   const hasLon = lon !== null && lon.length > 0;
   if (hasLat !== hasLon) {
-    out["location"] = mirrored(LISTINGS_I18N_KEYS.composeGeoIncomplete);
+    out[LOCATION_FIELD] = mirrored(LISTINGS_I18N_KEYS.composeGeoIncomplete);
   }
 
   return out;
@@ -244,6 +289,44 @@ export function publishRefusal(thrown: unknown): PublishRefusal {
   };
 }
 
+/**
+ * A per-field refusal in the ORDINARY envelope → the control it belongs to.
+ *
+ * `save-draft` and `create` do not answer a batch: DRF's field validation
+ * raises, and stapel-core's handler folds it into one envelope carrying
+ * `params.field` — the field name, and often the ONLY thing in the response
+ * that says what went wrong, because a DRF code the registry does not know
+ * (`max_decimal_places`, say) collapses to the generic
+ * `error.400.validation_error`, whose sentence is "Validation error" and
+ * nothing else.
+ *
+ * So the field name is the payload. Put on the control, it is the difference
+ * between a red banner the person cannot act on and a red field they can.
+ * Returns `{}` for anything that names no field, or names one this composer
+ * does not draw — a banner is right for those, and a refusal routed to a
+ * control that does not exist would vanish.
+ */
+export function envelopeFieldErrors(
+  thrown: unknown
+): Readonly<Record<string, FlowError>> {
+  if (!isStapelApiError(thrown)) return {};
+  const named = thrown.params["field"];
+  if (typeof named !== "string" || named.length === 0) return {};
+  const control = CONTROL_OF_API_FIELD[named];
+  if (control === undefined) return {};
+  return {
+    [control]: {
+      code: thrown.code,
+      // `field` is the fleet's routing param; the control key is what a
+      // sentence should name, not the column the server happened to use.
+      params: { ...thrown.params, field: control },
+      status: thrown.status,
+      message: thrown.message,
+      language: thrown.language,
+    },
+  };
+}
+
 /**
  * A server batch → refusals keyed by CONTROL.
  *

package/src/nav/manifest.ts

@@ -60,6 +60,7 @@ export const navEntries: readonly NavEntry[] = [
   {
     id: "listings.compose",
     labelKey: "listings.nav.compose",
+    shortLabelKey: "listings.nav.compose.short",
     icon: "PlusOutlined",
     route: { path: "/new" },
     component: { export: "ListingComposerPage", subpath: "default" },
@@ -73,6 +74,7 @@ export const navEntries: readonly NavEntry[] = [
     // Relative path: a child of the container's `/account` layout route.
     id: "listings.mine",
     labelKey: "listings.nav.mine",
+    shortLabelKey: "listings.nav.mine.short",
     icon: "ProfileOutlined",
     route: { path: "listings" },
     component: { export: "MyListingsPane", subpath: "default" },