@stapel/listings-react 0.14.0 → 0.15.0

package/src/api/generated/schema.ts

@@ -408,6 +408,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -433,6 +437,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -464,6 +472,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -539,6 +551,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -568,6 +584,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -595,6 +615,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -618,6 +642,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -649,6 +677,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -672,6 +704,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -707,8 +743,36 @@ export interface components {
             price_base?: string | null;
             currency?: string;
             readonly images: string[] | null;
-            readonly features_title: components["schemas"]["FeatureDao"][];
-            readonly features_badges: components["schemas"]["FeatureDao"][];
+            readonly features_title: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
+            readonly features_badges: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
             location_label?: string;
             geohash?: string;
             /** Format: decimal */
@@ -743,9 +807,51 @@ export interface components {
             lat?: string | null;
             /** Format: decimal */
             lon?: string | null;
-            readonly features: components["schemas"]["FeatureDao"][];
-            readonly features_title: components["schemas"]["FeatureDao"][];
-            readonly features_badges: components["schemas"]["FeatureDao"][];
+            readonly features: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
+            readonly features_title: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
+            readonly features_badges: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
             readonly features_search: unknown;
             status?: components["schemas"]["StatusD41Enum"];
             moderation_status?: components["schemas"]["ModerationStatusEnum"];
@@ -853,8 +959,36 @@ export interface components {
             price_base?: string | null;
             currency?: string;
             readonly images: string[] | null;
-            readonly features_title: components["schemas"]["FeatureDao"][];
-            readonly features_badges: components["schemas"]["FeatureDao"][];
+            readonly features_title: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
+            readonly features_badges: (components["schemas"]["FeatureDao"] | {
+                slug?: string;
+                type?: string;
+                name?: string | null;
+                order?: number | null;
+                translate?: string | null;
+                /** @enum {unknown} */
+                visibility?: "owner" | "staff";
+                verification?: {
+                    [key: string]: unknown;
+                };
+                /** @constant */
+                redacted: true;
+                present: boolean;
+            })[];
             location_label?: string;
             geohash?: string;
             /** Format: decimal */
@@ -955,6 +1089,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -981,6 +1119,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -1007,12 +1149,17 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}
              */
             type: "select";
             value?: string[];
+            labels?: string[];
             uiStyle?: (components["schemas"]["UiStyleEnum"] | components["schemas"]["NullEnum"]) | null;
             maxSelected?: number | null;
         };
@@ -1045,6 +1192,10 @@ export interface components {
             title?: boolean | null;
             badge?: boolean | null;
             translate?: string | null;
+            visibility?: string | null;
+            verification?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * @description discriminator enum property added by openapi-typescript
              * @enum {string}

package/src/api/types.ts

@@ -194,6 +194,35 @@ export interface ListingFeatureDao {
   /** Rendered as a badge on the card. */
   readonly badge?: boolean | null;
   readonly translate?: string | null;
+  /**
+   * Which audience may READ the stored value (stapel-attributes 0.8.1).
+   * Stamped into the DAO at write time and absent on a public row, so an
+   * existing row is byte-identical. `owner`/`staff` mark an identifier of one
+   * physical unit — a VIN, an IMEI, a serial — which stapel-listings 0.12.0
+   * withholds from a reader who is not entitled to it.
+   */
+  readonly visibility?: string | null;
+  /**
+   * `true` on a **stub**: the row survived redaction as its own identity with
+   * no value at all (`RedactedFeatureDao`). It is kept in place and in order
+   * so the public spec table has the same rows as the seller's own — a buyer
+   * can see the field exists rather than not knowing it was ever asked.
+   */
+  readonly redacted?: boolean;
+  /**
+   * On a stub: whether the seller actually filled the withheld value in.
+   * A FACT this system observed, and the only one it has — see
+   * {@link ListingFeatureDao.verification}.
+   */
+  readonly present?: boolean;
+  /**
+   * On a stub: the result of an outside check of the value, passed through
+   * redaction verbatim. **Absent for everything in the fleet today** — no
+   * product runs a VIN or an IMEI check — which is exactly why `present`
+   * alone may never be rendered as "verified". stapel-attributes deliberately
+   * leaves the `status` vocabulary to whichever product runs the check.
+   */
+  readonly verification?: Readonly<Record<string, unknown>>;
   /** The type's own config keys (`prefix`, `precision`, `unitType`, …). */
   readonly [key: string]: unknown;
 }

package/src/default/ListingDetailPane.tsx

@@ -50,10 +50,10 @@ import {
 } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
 import { FeatureValueList } from "@stapel/attributes-react/default";
-import { formatFeatureValue } from "@stapel/attributes-react";
+import { formatFeatureValue, isRedactedValue } from "@stapel/attributes-react";
 import { useListingDetail } from "../headless/ListingDetail.js";
 import { useListingActions } from "../headless/ListingActions.js";
-import { asFeatureDaoList, featuresDtoFromDaoList } from "../model/features.js";
+import { asFeatureDaoList, featureValuesForDisplay } from "../model/features.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { HeartIcon } from "./icons.js";
 import { ListingPhoto } from "./ListingPhoto.js";
@@ -218,6 +218,14 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               {bag.titleFeatures.length > 0 ? (
                 <Typography.Text type="secondary" data-testid="listings-detail-title-features">
                   {bag.titleFeatures
+                    // A hidden value is never part of a title: the server
+                    // keeps one out of `features_title` entirely, and
+                    // `formatFeatureValue` refuses a stub besides (it carries
+                    // no value, so there is nothing to format). The filter is
+                    // the third belt, and it is here rather than at the
+                    // formatter's edge because THIS is the line where a
+                    // leaked identifier would be read out loud.
+                    .filter((view) => !isRedactedValue(view.value))
                     .map((view) =>
                       formatFeatureValue(view.feature, view.value, { t, locale })
                     )
@@ -332,8 +340,15 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               ) : (
                 <FeatureValueList
                   features={bag.features.map((view) => view.feature)}
-                  values={featuresDtoFromDaoList(
-                    asFeatureDaoList(listing.features)
+                  // The DISPLAY envelope, not the edit one: a redacted row
+                  // keeps its place in the table and says the seller supplied
+                  // the value. `featuresDtoFromDaoList` deliberately drops a
+                  // stub, because it is what seeds a composer.
+                  values={featureValuesForDisplay(
+                    asFeatureDaoList(listing.features),
+                    props.categoryFeatures !== undefined
+                      ? { categoryFeatures: props.categoryFeatures }
+                      : {}
                   )}
                 />
               )}

package/src/index.ts

@@ -148,6 +148,7 @@ export type {
 export {
   asFeatureDaoList,
   featureFromDao,
+  featureValuesForDisplay,
   featuresDtoFromDaoList,
   featuresFromDaoList,
   unreadableFeatureCount,

package/src/model/features.ts

@@ -97,7 +97,7 @@
  * and an unknown key resolves to itself either way.
  */
 import type { FeatureDef, FeatureValueDto } from "@stapel/attributes-react";
-import { featureType } from "@stapel/attributes-react";
+import { featureType, isRedactedValue } from "@stapel/attributes-react";
 import type { ListingFeatureDao, ListingFeatureView } from "../api/types.js";
 
 /**
@@ -111,7 +111,30 @@ import type { ListingFeatureDao, ListingFeatureView } from "../api/types.js";
  * 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"]);
+const ENVELOPE = new Set([
+  "slug",
+  "value",
+  "name",
+  "order",
+  "title",
+  "badge",
+  // ── The visibility axis (stapel-attributes 0.8.1 / stapel-listings 0.12.0) ──
+  //
+  // These four are envelope for exactly the reason the six above are: they
+  // describe the ROW, not the type, and no formatter has ever read one. But
+  // they matter more than the others, because the alternative is not noise —
+  // it is a marker reaching the display BY ACCIDENT, through the index
+  // signature, with nothing stating that it did.
+  //
+  // `visibility` is a genuine `FeatureDef` field and is lifted onto the
+  // definition below; `redacted`/`present`/`verification` describe THIS
+  // reader's access to THIS stored value, so they ride the value envelope,
+  // which is where `@stapel/attributes-react`'s predicates read them.
+  "visibility",
+  "redacted",
+  "present",
+  "verification",
+]);
 
 /** 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.
@@ -139,6 +162,32 @@ function isTranslateMode(value: unknown): value is "all" | "title" | "none" {
   return value === "all" || value === "title" || value === "none";
 }
 
+/**
+ * The stamped `FeatureDef.visibility`, or `undefined` when the row is public.
+ *
+ * `public` is stamped as nothing at all upstream (`dataclass_to_dict_no_none`
+ * drops it), which is why an existing public row is byte-identical after the
+ * axis landed — so an absent key means public and is dropped here too.
+ *
+ * A string that is NOT one of the three becomes `"staff"`, the most
+ * restrictive one. Python raises `UnknownVisibility` on the same input; this
+ * side has nobody to raise at, so it takes the only direction that cannot
+ * leak — a typo must not publish a VIN. The engine normalizes at write time,
+ * so this is the belt on a stored row nobody expects to see.
+ */
+function storedVisibility(value: unknown): "public" | "owner" | "staff" | undefined {
+  if (typeof value !== "string" || value.length === 0 || value === "public") return undefined;
+  return value === "owner" || value === "staff" ? value : "staff";
+}
+
+/** A `verification` result, when the row carries one. An object and nothing
+ * else: the shape belongs to whichever product ran the check, and this
+ * projection passes it through rather than describing it. */
+function storedVerification(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Readonly<Record<string, unknown>>;
+}
+
 /**
  * The category's feature defs, for a display surface that has them.
  *
@@ -317,6 +366,7 @@ function featureView(
     selectOptions(dao, config, categoryDef) ?? adoptedTree(dao, config, categoryDef);
   if (options !== undefined) config["options"] = options;
 
+  const visibility = storedVisibility(dao.visibility);
   const feature: FeatureDef = {
     slug: dao.slug,
     config,
@@ -326,8 +376,38 @@ function featureView(
     // the three is dropped rather than smuggled through: `FeatureDef`'s own
     // default is `all`, which is what the engine falls back to anyway.
     ...(isTranslateMode(dao.translate) ? { translate: dao.translate } : {}),
+    // A genuine `FeatureDef` field, so it goes on the DEFINITION rather than
+    // into `config`: it is what `isPublicFeature` reads to keep a hidden
+    // value off a badge strip.
+    ...(visibility !== undefined ? { visibility } : {}),
   };
 
+  // A REDACTED STUB — a row this reader may not see — carries no `value` key
+  // at all, and this envelope must not invent one. What it carries instead is
+  // what the system honestly observed: `present` (did the seller answer) and,
+  // reserved for the day some product actually runs a VIN or an IMEI check,
+  // `verification`. `@stapel/attributes-react`'s `<FeatureValueList/>` reads
+  // exactly these and prints "provided by the seller" — never "verified".
+  //
+  // The row is built even when `type` is missing, which the normal path below
+  // refuses: an unkeyable value is a row a buyer cannot be told about, but a
+  // stub's whole content is "this field exists and was answered", and that is
+  // still true without a type slug.
+  if (dao.redacted === true) {
+    const verification = storedVerification(dao.verification);
+    const stub: FeatureValueDto = {
+      type: typeof dao.type === "string" ? dao.type : "",
+      // No stored answer exists on this side of the wire. Spelled rather than
+      // omitted only because `FeatureValueDto.value` is a required key;
+      // `isBlank(undefined)` is true, so no formatter prints anything for it.
+      value: undefined,
+      redacted: true,
+      present: dao.present === true,
+      ...(verification !== undefined ? { verification } : {}),
+    };
+    return { feature, value: stub };
+  }
+
   const value: FeatureValueDto | undefined =
     typeof dao.type === "string" && dao.type.length > 0
       ? { type: dao.type, value: dao.value }
@@ -365,12 +445,55 @@ export function unreadableFeatureCount(
  * a composer reopening a PUBLISHED listing needs: `draftValuesFromDetail`
  * seeds its editors from the published values, and the published values live
  * only in the DAO list.
+ *
+ * ── Why a redacted stub is DROPPED here, and not passed through ────────────
+ *
+ * This is the EDIT envelope, and the only one that can destroy data. A stub
+ * has no value; seeding an editor from it would put `undefined` in the
+ * composer's draft under the seller's own slug, and the next save would write
+ * that back — blanking a stored VIN the seller never touched and cannot see
+ * was blanked. Dropping the row instead leaves the field empty in the form
+ * and untouched in the record, which is the recoverable failure.
+ *
+ * A composer reopening a listing belongs to its OWNER, whose read is
+ * unredacted, so a stub reaching this function means something upstream
+ * already went wrong — a cached anonymous payload, a viewer id that did not
+ * arrive, a host wiring the public detail into an edit form. It fails safe
+ * rather than fails loudly on purpose: there is no honest recovery from "the
+ * value was withheld from the person editing it", and refusing the whole seed
+ * would take the other twenty answers down with it.
+ *
+ * {@link featureValuesForDisplay} is the other half of this split: a spec
+ * table WANTS the stub, because "the seller answered this" is exactly what it
+ * has to say.
  */
 export function featuresDtoFromDaoList(
   daos: readonly ListingFeatureDao[] | null | undefined
 ): Readonly<Record<string, FeatureValueDto>> {
   const out: Record<string, FeatureValueDto> = {};
   for (const view of featuresFromDaoList(daos)) {
+    if (view.value === undefined || isRedactedValue(view.value)) continue;
+    out[view.feature.slug] = view.value;
+  }
+  return out;
+}
+
+/**
+ * A stored projection → the envelope a DISPLAY component reads, redacted
+ * stubs and all.
+ *
+ * Same shape as {@link featuresDtoFromDaoList} and a different job, which is
+ * why it is a different function rather than a flag: a stub belongs in a spec
+ * table (in place, in order, saying the seller answered) and must never reach
+ * an editor. A boolean argument would put the destructive default one
+ * forgotten parameter away.
+ */
+export function featureValuesForDisplay(
+  daos: readonly ListingFeatureDao[] | null | undefined,
+  source: FeatureCopySource = {}
+): Readonly<Record<string, FeatureValueDto>> {
+  const out: Record<string, FeatureValueDto> = {};
+  for (const view of featuresFromDaoList(daos, source)) {
     if (view.value !== undefined) out[view.feature.slug] = view.value;
   }
   return out;