@stapel/listings-react 0.23.0 → 0.24.0

package/src/index.ts

@@ -166,6 +166,21 @@ export {
   unreadableFeatureCount,
 } from "./model/features.js";
 export type { FeatureCopySource } from "./model/features.js";
+export { featureUnit, formatSpecValue } from "./model/featureText.js";
+
+// ── model: the card badge contract (stapel-listings 0.21.3) ──────────────────
+export {
+  badgePresentation,
+  badgeValueText,
+  cardBadgeText,
+  cardBadgeTexts,
+  hasCardBadgeContract,
+} from "./model/cardBadges.js";
+export type {
+  CardBadgeContract,
+  CardBadgePresentation,
+  CardBadgeRow,
+} from "./model/cardBadges.js";
 
 // ── model: the engagement axis (already-seen / view count / the overlay) ─────
 export {

package/src/model/cardBadges.ts

@@ -0,0 +1,237 @@
+/**
+ * The CARD BADGE CONTRACT — what a badge on a result card is allowed to say.
+ *
+ * ── What was on screen ────────────────────────────────────────────────────
+ *
+ * A live card's badge line read "Brick · 3 · 9". Three true facts about a
+ * flat, and two of them unreadable: 3 what, 9 what. The projection carried
+ * the VALUES and the display half printed them, because that is all a stored
+ * `features_badges` row could offer — a number with no unit and no question
+ * beside it.
+ *
+ * stapel-listings 0.21.3 adds the missing half to each element:
+ *
+ *   `value`         the raw answer
+ *   `label`         its resolved copy, where the answer is an option
+ *   `unit`          what the number is measured in
+ *   `name`          the question — the feature's own display name
+ *   `presentation`  which of those to print, decided by the SERVER
+ *
+ * `presentation` is the load-bearing key, and it is the server's decision
+ * rather than a rule guessed here, because the right badge for a value
+ * depends on the CATEGORY: "3 rooms" wants its name, "Brick" is a
+ * boolean whose name IS the badge, "20 000 km" wants its unit and no name at
+ * all, and no client-side heuristic gets all three right for every catalogue
+ * in the fleet.
+ *
+ * ── The four presentations ───────────────────────────────────────────────
+ *
+ *   `value`       the value alone      — "Brick" (an option label)
+ *   `value_unit`  value and unit       — "20 000 km"
+ *   `name_value`  name and value       — "Floor 3": a SPACE and never a colon,
+ *                                        because a card is a caption and not a
+ *                                        form. The unit is kept when the
+ *                                        element carries one — a named row
+ *                                        that dropped it reads "Mileage 20 000"
+ *   `name`        the name alone       — a TRUE boolean, whose whole content
+ *                                        is that the flat is brick. A FALSE
+ *                                        one renders nothing: "not brick" is
+ *                                        not a selling point, and a card is a
+ *                                        summary rather than a form.
+ *
+ * ── Why a local type extension and not a regenerated schema ───────────────
+ *
+ * The generated `FeatureDao` union is already unusable on this side (the
+ * discriminator defect, `api/types.ts`), `features_badges` is a `JSONField`
+ * on the serializer, and this pair reads the row through
+ * {@link ListingFeatureDao} — a hand-written mirror of the runtime shape —
+ * for exactly that reason. The contract is an additive extension of the same
+ * mirror, so a regeneration cannot take it away and an older backend that
+ * sends none of the five keys is simply a row where
+ * {@link hasCardBadgeContract} is false.
+ *
+ * ── The fallback is the whole compatibility story ─────────────────────────
+ *
+ * A row with no `presentation` is a row from a server that predates the
+ * contract, and it is rendered exactly as it is rendered today — through
+ * `@stapel/attributes-react`'s `<FeatureBadges>`, off the stored DAO's own
+ * config. Nothing about this module is required for a card to draw.
+ */
+import type { ListingCardBadgeElement, ListingFeatureDao } from "../api/types.js";
+
+/**
+ * Which parts of a badge element the server asked to be printed.
+ *
+ * Read off the GENERATED element rather than spelled again here: the four
+ * readings are the server's enum, and a fifth added upstream must turn this
+ * build red instead of falling through {@link badgePresentation}'s default in
+ * silence.
+ */
+export type CardBadgePresentation = ListingCardBadgeElement["presentation"];
+
+/**
+ * The keys stapel-listings 0.21.3 adds to a `features_badges` /
+ * `features_title` element.
+ *
+ * The NAMES and their types come from the generated element; the optionality
+ * is this pair's own, and is the whole compatibility story — the contract
+ * makes them required, and a server that predates it sends none of them. Same
+ * argument as {@link ListingEngagementFields}, one file over: a generated type
+ * is a promise about the contract, not about the bytes a deployment sends.
+ */
+export type CardBadgeContract = {
+  /** The raw answer. Absent on a redacted row, which is why the renderers
+   * below all tolerate it, and `unknown` because the DAO union types it per
+   * feature type and a badge prints whatever it was given. */
+  readonly value?: unknown;
+} & {
+  readonly [K in "label" | "unit" | "name"]?: ListingCardBadgeElement[K] | null;
+} & {
+  /** Widened back to `string` on purpose: {@link badgePresentation} exists to
+   * REFUSE a reading it does not know, and a field typed as the four would
+   * make that refusal unreachable — and untestable — while a server is still
+   * free to send a fifth. */
+  readonly presentation?: string | null;
+};
+
+/** A stored badge row, with the contract's keys where the server sends them. */
+export type CardBadgeRow = ListingFeatureDao & CardBadgeContract;
+
+/**
+ * `presentation` as one of the four, or `undefined`.
+ *
+ * An unrecognised spelling is `undefined` rather than a guess: the whole
+ * point of the key is that the SERVER decided, and a client that invented a
+ * fifth reading would print one category's rule on another category's card.
+ */
+export function badgePresentation(row: CardBadgeRow): CardBadgePresentation | undefined {
+  const raw = row.presentation;
+  if (typeof raw !== "string") return undefined;
+  switch (raw) {
+    case "value":
+    case "value_unit":
+    case "name_value":
+    case "name":
+      return raw;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Does this projection speak the contract at all?
+ *
+ * ONE row declaring a `presentation` is enough: the server writes the whole
+ * list in one pass, so a mixed list means a row the server deliberately left
+ * plain, and that row still renders (as its value alone) rather than
+ * dragging the other four back to the old path.
+ */
+export function hasCardBadgeContract(rows: readonly CardBadgeRow[]): boolean {
+  return rows.some((row) => badgePresentation(row) !== undefined);
+}
+
+/** Trimmed copy, or `""` — `null` is the shape the wire uses for absent. */
+function text(value: string | null | undefined): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * How many decimals the wire actually stated.
+ *
+ * A card badge must not invent precision and must not lose it: the server
+ * sends "2.0" for an engine volume and `2` for a number of rooms, and JS
+ * cannot tell `2.0` from `2` once it is a number — so a STRING value keeps
+ * the decimals it was written with and a number keeps its own.
+ */
+function statedDecimals(raw: unknown): number {
+  const written = typeof raw === "string" ? raw : String(raw);
+  const tail = written.split(".")[1];
+  return tail === undefined ? 0 : tail.replace(/[^0-9]/g, "").length;
+}
+
+/**
+ * The element's answer, as a person reads it: the server's `label` when there
+ * is one, the value with its digits grouped when it is a number, the value
+ * verbatim otherwise.
+ */
+export function badgeValueText(row: CardBadgeRow, locale?: string): string {
+  const label = text(row.label);
+  if (label.length > 0) return label;
+  const raw = row.value;
+  if (raw === null || raw === undefined || raw === "") return "";
+  if (typeof raw === "boolean") return "";
+  const parsed = typeof raw === "number" ? raw : Number(raw);
+  if (typeof raw !== "object" && Number.isFinite(parsed)) {
+    const digits = statedDecimals(raw);
+    try {
+      return new Intl.NumberFormat(locale, {
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+      }).format(parsed);
+    } catch {
+      return parsed.toFixed(digits);
+    }
+  }
+  return typeof raw === "object" ? "" : String(raw);
+}
+
+/** Is this element's value the `true` a `name`-presented boolean needs? */
+function isTrue(raw: unknown): boolean {
+  return raw === true || raw === 1 || raw === "true";
+}
+
+/**
+ * One badge element → the text a card prints, or `undefined` for an element
+ * that has nothing to say (a false boolean, a blank value).
+ *
+ * The one place the four presentations are read. Every card surface calls
+ * this and none of them re-derives it, for the same reason `CardTarget`
+ * exists: three cards each re-deciding what a badge says is three places for
+ * "Brick · 3 · 9" to come back.
+ */
+export function cardBadgeText(row: CardBadgeRow, locale?: string): string | undefined {
+  const presentation = badgePresentation(row);
+  const name = text(row.name);
+  const unit = text(row.unit);
+
+  if (presentation === "name") {
+    // The name IS the badge, and only while the answer is yes.
+    return isTrue(row.value) && name.length > 0 ? name : undefined;
+  }
+
+  const value = badgeValueText(row, locale);
+  if (value.length === 0) return undefined;
+
+  const withUnit = unit.length > 0 ? `${value} ${unit}` : value;
+
+  switch (presentation) {
+    case "value_unit":
+      return withUnit;
+    case "name_value":
+      // A SPACE, not a colon. "Floor 3" is a caption; "Floor: 3" is a form
+      // field, and a card is neither a form nor a table — the colon is the
+      // punctuation the spec list uses because a spec list IS the table.
+      // The unit rides along: a named row that dropped it reads "Mileage
+      // 20 000", which is the defect this contract exists to close.
+      return name.length > 0 ? `${name} ${withUnit}` : withUnit;
+    default:
+      // `value`, and an element the server left plain in a list that speaks
+      // the contract. The value alone, never the unit — the server said so.
+      return value;
+  }
+}
+
+/** Every element that has something to say, in the server's order. */
+export function cardBadgeTexts(
+  rows: readonly CardBadgeRow[],
+  locale?: string
+): readonly { readonly slug: string; readonly text: string }[] {
+  const out: { slug: string; text: string }[] = [];
+  for (const row of rows) {
+    const printed = cardBadgeText(row, locale);
+    if (printed !== undefined && typeof row.slug === "string" && row.slug.length > 0) {
+      out.push({ slug: row.slug, text: printed });
+    }
+  }
+  return out;
+}

package/src/model/featureText.ts

@@ -0,0 +1,199 @@
+/**
+ * A stored feature value as a person READS it — with its unit, and with its
+ * digits grouped the way the reader's locale groups them.
+ *
+ * ── What was on screen ────────────────────────────────────────────────────
+ *
+ * Measured on the live listing page: "Power 173", "Mileage 20000", "Engine
+ * volume 2.0". Three defects in three rows:
+ *
+ *  - **no unit.** 173 what. 20000 what. A spec row whose value is a bare
+ *    number is a row a buyer has to guess at, and mileage is the single
+ *    number a used-car buyer decides on;
+ *  - **no digit grouping.** `20000` is read digit by digit; "20 000" is read
+ *    at a glance. `formatFeatureValue`'s integer branch is `String(value)`
+ *    (attributes-react `src/format.ts:196`), deliberately — it mirrors the
+ *    engine's own `str(value)` — and the engine renders for a machine-read
+ *    API, not for a spec table;
+ *  - **the wrong decimal mark.** `2.0` in a Russian storefront. The engine
+ *    writes `toFixed`, which is invariant by construction.
+ *
+ * ── Where the unit comes from ─────────────────────────────────────────────
+ *
+ * There is NO generic `unit` key anywhere in this fleet's feature contract —
+ * not on `FeatureDef` (`stapel-attributes/base.py:154-208`), not on
+ * `IntConfig`/`FloatConfig` (`attributes-react/src/generated/featureDef.ts:163`),
+ * not on the stored DAO. The unit of an `int`/`float` IS its `postfix`, free
+ * text on the type's config, with `postfix1000` as the abbreviated unit the
+ * engine switches to at a thousand. `convertible_unit` is the one type with
+ * real unit semantics (`unitType`/`unit_m`/`unit_i`), and its own formatter
+ * already appends the resolved code — so this module leaves it alone.
+ *
+ * So "render the unit from the definition" means: read `postfix`. It reaches
+ * a display surface two ways, and `model/features.ts` now tries both — the
+ * stored row's own config first (`dto_to_dao` copies `postfix` at write
+ * time), then the CATEGORY's definition of the same slug, which is the path
+ * that repairs every listing published before a catalogue gained its units.
+ *
+ * ── Why the whole formatter is not delegated ──────────────────────────────
+ *
+ * `formatFeatureValue` is the fleet's one formatter and stays it: every type
+ * but `int` and `float` goes straight through it, untouched. The two numeric
+ * types are intercepted because the change is not a different ANSWER, it is
+ * the same answer typeset — same value, same precision rule, same
+ * `postfix1000` switch at a thousand, same translated unit, with the digits
+ * run through `Intl.NumberFormat` instead of `String()`.
+ */
+import type { FeatureDef, FeatureValueDto, FormatOptions } from "@stapel/attributes-react";
+import { featureConfig, featureType, formatFeatureValue } from "@stapel/attributes-react";
+
+/** The engine's own defaults (`types/int/type.py`, `types/float/type.py`). */
+const DEFAULT_DIGITS: Readonly<Record<"int" | "float", number>> = {
+  int: 1,
+  float: 2,
+};
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * A config string the engine declares to be a translation key, resolved.
+ *
+ * `prefix`/`postfix`/`postfix1000` are collected by upstream's
+ * `get_translation_keys` unconditionally, so they go through the host's
+ * catalogue exactly as `formatFeatureValue` sends them — a Russian storefront
+ * was reading "L" and "each" off its own spec table before that landed, and
+ * this path must not reintroduce it.
+ */
+function translated(options: FormatOptions | undefined, raw: unknown): string {
+  const text = str(raw);
+  if (text.length === 0) return "";
+  const t = options?.t;
+  if (t === undefined) return text;
+  const resolved = t(text);
+  return resolved.length > 0 ? resolved : text;
+}
+
+/**
+ * The unit a numeric feature is measured in, as the reader sees it — or `""`.
+ *
+ * `postfix1000` when the engine's own thousand switch applies, `postfix`
+ * otherwise, so the unit and the number can never disagree about scale.
+ */
+export function featureUnit(
+  feature: FeatureDef,
+  dto: FeatureValueDto | undefined,
+  options?: FormatOptions
+): string {
+  const type = featureType(feature);
+  if (type !== "int" && type !== "float") return "";
+  const config = featureConfig(feature);
+  const parsed = Number(dto?.value);
+  const big = str(config["postfix1000"]).length > 0 && Number.isFinite(parsed) && Math.abs(parsed) >= 1000;
+  return translated(options, config[big ? "postfix1000" : "postfix"]);
+}
+
+/**
+ * `Intl.NumberFormat` for one value, or `undefined` when the runtime has no
+ * `Intl` for this locale to offer.
+ *
+ * A bad BCP-47 tag throws `RangeError`, and a spec table that renders nothing
+ * because a host passed `"en_US"` would be a worse outcome than an ungrouped
+ * number — so the caller falls back rather than the page failing.
+ */
+function grouped(value: number, digits: number, locale: string | undefined): string | undefined {
+  try {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: digits,
+      maximumFractionDigits: digits,
+    }).format(value);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The one numeric row, typeset — see the module header for what each piece
+ * is repairing.
+ *
+ * Returns `undefined` for a value that is not a number, so the caller falls
+ * back to the shared formatter and an unreadable row keeps saying so.
+ */
+function formatNumeric(
+  feature: FeatureDef,
+  dto: FeatureValueDto,
+  kind: "int" | "float",
+  options: FormatOptions | undefined
+): string | undefined {
+  // `Number(null)` is 0 and `Number("")` is 0, so a blank row would render as
+  // a confident zero. The shared formatter's own `isBlank` gate is upstream of
+  // this branch and must be restated here rather than assumed.
+  const raw = dto.value;
+  if (raw === null || raw === undefined || raw === "") return undefined;
+  const parsed = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(parsed)) return undefined;
+  const config = featureConfig(feature);
+  const precision = config["precision"];
+  const digits =
+    typeof precision === "number" && precision >= 0 ? precision : DEFAULT_DIGITS[kind];
+
+  const prefix = translated(options, config["prefix"]);
+  const postfix1000 = str(config["postfix1000"]);
+
+  // The engine switches unit AND scale at exactly a thousand
+  // (`format_value`: `value / 1000`, trailing zeros stripped, `postfix1000`
+  // as the unit). Grouping a scaled number is harmless and keeps one code
+  // path; the trailing-zero strip is the engine's, done on the plain digits
+  // before the locale ever sees them, because "1.50" and "1,5" are the same
+  // decision made in two places.
+  if (postfix1000.length > 0 && Math.abs(parsed) >= 1000) {
+    const scaled = Number((parsed / 1000).toFixed(digits));
+    const body =
+      grouped(scaled, decimalsOf(scaled, digits), options?.locale) ?? String(scaled);
+    return join(prefix, body, translated(options, postfix1000));
+  }
+
+  // `precision` drives ONLY the scaled branch of an int — the engine's plain
+  // branch is `str(value)`, and an integer never grows a decimal tail
+  // whatever the config says (D26: a live category shipped `precision: 1` on
+  // a year field and the card read "2024.0").
+  const value = kind === "int" ? Math.trunc(parsed) : parsed;
+  const fraction = kind === "int" ? 0 : digits;
+  const body = grouped(value, fraction, options?.locale) ?? value.toFixed(fraction);
+  return join(prefix, body, translated(options, config["postfix"]));
+}
+
+/** How many decimals a scaled value actually has, capped at the configured
+ * precision — the engine's `.rstrip('0').rstrip('.')`, expressed as a count
+ * so `Intl` can do the rendering. */
+function decimalsOf(value: number, cap: number): number {
+  const tail = value.toFixed(cap).split(".")[1] ?? "";
+  return tail.replace(/0+$/, "").length;
+}
+
+/** `prefix` + body + unit, with the single space the engine puts between a
+ * number and its unit and no space at all where there is no unit. */
+function join(prefix: string, body: string, unit: string): string {
+  return unit.length > 0 ? `${prefix}${body} ${unit}` : `${prefix}${body}`;
+}
+
+/**
+ * A stored value as a spec row prints it: `formatFeatureValue` for every type
+ * but the two numeric ones, which are typeset here instead.
+ *
+ * Signature-compatible with `formatFeatureValue` on purpose — a surface
+ * swaps one for the other and nothing else changes.
+ */
+export function formatSpecValue(
+  feature: FeatureDef,
+  dto: FeatureValueDto | undefined,
+  options?: FormatOptions
+): string | undefined {
+  const type = featureType(feature);
+  if (dto !== undefined && (type === "int" || type === "float")) {
+    const typeset = formatNumeric(feature, dto, type, options);
+    if (typeset !== undefined) return typeset;
+  }
+  return formatFeatureValue(feature, dto, options);
+}

package/src/model/features.ts

@@ -317,6 +317,64 @@ function selectOptions(
   return [...table].map(([value, label]) => ({ value, label }));
 }
 
+/**
+ * The config keys that carry a value's UNIT, in the order they belong to.
+ *
+ * There is no generic `unit` key anywhere in this contract — the unit of an
+ * `int`/`float` is its `postfix` (free text on the type's config, with
+ * `postfix1000` as the abbreviated unit the engine switches to at a
+ * thousand), and `convertible_unit` states its own with `unitType`/`unit_m`/
+ * `unit_i`. `prefix` rides along because it is the same fact on the other
+ * side of the number (a currency mark, a «~»).
+ *
+ * `precision` is deliberately NOT here. `dto_to_dao` writes it on every
+ * numeric row (defaulted, never absent), so it could only ever be adopted
+ * onto a row from some older server — where the stored value has already
+ * been ROUNDED to the precision it was written with, and re-rendering it at
+ * today's would print decimals the record does not contain.
+ */
+const UNIT_KEYS: readonly string[] = [
+  "prefix",
+  "postfix",
+  "postfix1000",
+  "unitType",
+  "unit_m",
+  "unit_i",
+];
+
+/**
+ * The unit the CATEGORY declares, for a stored row that carries none.
+ *
+ * Measured on the live listing page: "Power 173", "Mileage 20000" — bare
+ * numbers, in a deployment whose detail page holds the category's own feature
+ * defs and passes them in for exactly this kind of repair. `dto_to_dao`
+ * copies `postfix` at WRITE time, so a listing published before its category
+ * gained a unit keeps printing without one for the rest of its life, and so
+ * does every row written by a server that predates the key.
+ *
+ * Same rule as the option table two functions up, and for the same reason:
+ * the stored row wins wherever it said anything, because it is what the
+ * listing was published with, and the category fills only the silence. An
+ * empty string counts as silence — `dto_to_dao` writes `postfix=None` as
+ * absent, but a catalogue that once held `""` should not out-rank a
+ * catalogue that now holds "km".
+ */
+function adoptedUnits(
+  config: Readonly<Record<string, unknown>>,
+  categoryDef: FeatureDef | undefined
+): Readonly<Record<string, string>> | undefined {
+  const declared = categoryDef?.config;
+  if (declared === undefined) return undefined;
+  const out: Record<string, string> = {};
+  for (const key of UNIT_KEYS) {
+    const stored = config[key];
+    if (typeof stored === "string" && stored.length > 0) continue;
+    const value = (declared as Readonly<Record<string, unknown>>)[key];
+    if (typeof value === "string" && value.length > 0) out[key] = value;
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
+}
+
 /**
  * The category's option TREE, adopted whole for a `hierarchical_select` that
  * stored none — see {@link TREE_VALUED}.
@@ -365,6 +423,8 @@ function featureView(
   const options =
     selectOptions(dao, config, categoryDef) ?? adoptedTree(dao, config, categoryDef);
   if (options !== undefined) config["options"] = options;
+  const units = adoptedUnits(config, categoryDef);
+  if (units !== undefined) Object.assign(config, units);
 
   const visibility = storedVisibility(dao.visibility);
   const feature: FeatureDef = {