@stapel/listings-react 0.11.0 → 0.13.0

package/src/default/ListingComposerPage.tsx

@@ -50,6 +50,45 @@
  * do not import each other; the container is the seam. A library that picked
  * one would pick it for every host.
  *
+ * ── The SECTION ORDER is this component's, and it is not a prop ────────────
+ *
+ * One order, at every width:
+ *
+ *   category → title → description → price → currency → where → photos →
+ *   the category's characteristics → the listing's own options
+ *
+ * The category comes first because everything after it depends on the choice.
+ * Then the five questions a seller came to answer — what it is, what it says,
+ * what it costs, where it is, what it looks like — and only then the questions
+ * the CATEGORY asks.
+ *
+ * This used to be two orders chosen by the form's width, and the narrow one
+ * put the characteristics directly under the category. The reason was real:
+ * measured on a live classified deployment, Mobile phones put the first
+ * attribute control at y=1596, two viewports below the fold, while the footer
+ * said "10 required details not filled in" with none of them on screen. The
+ * fix was not: the same leaf carries 32 imported fields, so on the next
+ * measurement of the same form the seller was asked for the parcel's weight,
+ * its length and "what the goods are measured in" BEFORE the title — title
+ * y=5575, price y=5871, photos y=6245, of a 7308px form. A composer that asks
+ * about postage before it asks what is being sold has no funnel left.
+ *
+ * So the discoverability problem is solved where it actually lives, and by two
+ * things that do not move the questions around:
+ *
+ *  - the count of unfilled details is a CONTROL that goes to the first of them
+ *    (`listings-composer-goto-missing`, below), so "10 required details" is
+ *    never a dead end wherever the region sits;
+ *  - the region itself is short, because `groupCollapse="auto"` opens the
+ *    groups that ask something required and leaves the plumbing (delivery
+ *    dimensions, wholesale terms) closed under its own heading.
+ *
+ * `detailsPlacement` is therefore gone as a decision — `data-placement` stays
+ * on the region as a constant, because an e2e that measured the regression
+ * needs something to read that is not a pixel count. A host that wants a
+ * different order does not want this page; it wants `<FeatureFields>` and its
+ * own form, which is exactly why that component is exported separately.
+ *
  * ── Every blocked control says which of six reasons it is ──────────────────
  *
  * The publish button is the most-gated control in the fleet, and that is the
@@ -63,6 +102,7 @@
 import type { ComponentType, ReactElement, ReactNode } from "react";
 import {
   Alert,
+  Button,
   Checkbox,
   Divider,
   Flex,
@@ -90,6 +130,7 @@ import type { FeatureDef } from "@stapel/attributes-react";
 import {
   BUILTIN_VALUE_EDITOR_TYPES,
   FeatureFields,
+  featureControlId,
 } from "@stapel/attributes-react/default";
 import { useListingComposer } from "../headless/ListingComposer.js";
 import type { ListingLocation } from "../model/draft.js";
@@ -114,6 +155,73 @@ import type { ThemeModeProp } from "./types.js";
  */
 export const COMPOSER_MEASURE = "44rem";
 
+/**
+ * What `data-placement` says on the characteristics region.
+ *
+ * A constant, and deliberately so: the order is the composer's and does not
+ * depend on the width any more (see the header). The attribute stays because
+ * an e2e suite measured the regression through it and needs a reading that is
+ * not a pixel count.
+ */
+export const COMPOSER_DETAILS_PLACEMENT = "after-core-fields";
+
+/**
+ * The DOM id of the control that answers one of the composer's own fields —
+ * the names `mirrorListingFields` refuses by (`title`, `description`, …).
+ *
+ * A person told "10 required details are still empty" needs to be taken to
+ * one, and taking them there needs an ADDRESS. Features already have one
+ * (`featureControlId`); the composer's own fields had none, and a test id is
+ * not an address — it is a test's handle, and reaching for it in product code
+ * makes every test id load-bearing.
+ */
+export function composerFieldId(field: string): string {
+  return `listings-composer-field-${field}`;
+}
+
+/** What counts as a control a person can be put in front of. A slot's control
+ * belongs to the container, so the field is asked for its first focusable
+ * descendant rather than assumed to be an `<input>`. */
+const FOCUSABLE =
+  "input,select,textarea,button,[href],[tabindex]:not([tabindex='-1'])";
+
+/**
+ * Put the person in front of one field: open whatever it is folded inside,
+ * bring it into view, and focus what they are meant to answer.
+ *
+ * The disclosure step is the one that is easy to forget. A characteristic
+ * lives in a `<details>` section that may be closed (`groupCollapse="auto"`),
+ * and scrolling to a control inside a closed disclosure scrolls to nothing —
+ * the "take me to the first empty field" button would report success and move
+ * the page nowhere. Any depth of nesting is opened, because the answer to
+ * "where is it" must not depend on how the section was drawn.
+ *
+ * The rest is guarded rather than assumed. `scrollIntoView` does not exist in
+ * every environment this renders in (jsdom, older embedded engines), and a
+ * field whose control came from a slot may have nothing focusable in it at
+ * all — in which case scrolling to it is still the whole of the help that can
+ * honestly be given.
+ */
+function revealField(id: string): void {
+  if (typeof document === "undefined") return;
+  const anchor = document.getElementById(id);
+  if (anchor === null) return;
+  for (
+    let folded = anchor.closest("details");
+    folded !== null;
+    folded = folded.parentElement?.closest("details") ?? null
+  ) {
+    folded.open = true;
+  }
+  if (typeof anchor.scrollIntoView === "function") {
+    anchor.scrollIntoView({ block: "center", behavior: "smooth" });
+  }
+  const control = anchor.matches(FOCUSABLE)
+    ? anchor
+    : anchor.querySelector<HTMLElement>(FOCUSABLE);
+  control?.focus();
+}
+
 /**
  * What `renderCategoryPicker` is handed: the current category and the ONLY
  * function that changes it. Same shape as any other bag in this monorepo — the
@@ -318,16 +426,23 @@ function SlotField(props: {
   readonly control: ReactNode | undefined;
   readonly status: { help: ReactNode; validateStatus: "error" } | Record<string, never>;
   readonly testId: string;
+  /** The address `revealField` aims at — see {@link composerFieldId}. */
+  readonly anchorId: string;
 }): ReactElement | null {
   const filled = props.control !== undefined;
   if (!filled && !props.named) return null;
+  // A refusal REPLACES the hint rather than stacking under it. "Choose a
+  // category — the rest of the form depends on it" and "a category is
+  // required" are one fact printed twice, one line apart, and the second is
+  // the one the person just earned.
+  const refused = "validateStatus" in props.status;
   return (
     <Form.Item
       label={props.label}
-      {...(props.extra !== undefined ? { extra: props.extra } : {})}
+      {...(props.extra !== undefined && !refused ? { extra: props.extra } : {})}
       {...props.status}
     >
-      <div data-testid={props.testId}>
+      <div id={props.anchorId} data-testid={props.testId}>
         {props.control ?? <SlotPlaceholder name={props.slot} visibility="visible" />}
       </div>
     </Form.Item>
@@ -401,6 +516,72 @@ export function ListingComposerPage(
   );
 
   const LocationPicker = props.locationPicker;
+
+  /**
+   * The characteristics of the chosen category — built once and rendered in
+   * exactly one of two places, so neither arm can drift from the other.
+   *
+   * The four states are four different sentences, and the one that used to be
+   * missing is the FIRST: with no category chosen there is no request in
+   * flight and none will be made, so "loading the category's characteristics"
+   * was simply untrue — a spinner-shaped sentence over a form that was waiting
+   * for the person, not for the network.
+   */
+  const details = (
+    <div
+      data-testid="listings-composer-details"
+      data-placement={COMPOSER_DETAILS_PLACEMENT}
+    >
+      <Divider />
+      <Typography.Title level={5}>
+        {t(LISTINGS_I18N_KEYS.composeDetails)}
+      </Typography.Title>
+      {props.featuresError !== undefined ? (
+        <ErrorAlert
+          testId="listings-composer-features-failed"
+          message={t(LISTINGS_I18N_KEYS.composeDetailsFailed)}
+        />
+      ) : bag.values.categoryId.length === 0 ? (
+        <Typography.Text
+          type="secondary"
+          data-testid="listings-composer-features-no-category"
+        >
+          {t(LISTINGS_I18N_KEYS.composeDetailsNoCategory)}
+        </Typography.Text>
+      ) : props.featuresLoading === true ? (
+        <Typography.Text type="secondary" data-testid="listings-composer-features-loading">
+          {t(LISTINGS_I18N_KEYS.composeDetailsLoading)}
+        </Typography.Text>
+      ) : props.features.length === 0 ? (
+        <Typography.Text type="secondary" data-testid="listings-composer-features-empty">
+          {t(LISTINGS_I18N_KEYS.composeDetailsEmpty)}
+        </Typography.Text>
+      ) : (
+        <FeatureFields
+          features={props.features}
+          values={bag.values.features}
+          errors={bag.fieldErrors}
+          disabled={bag.publishing}
+          onChange={bag.setFeature}
+          // An imported leaf is mostly plumbing: 32 fields across seven
+          // headings, four of them parcel dimensions. Open what is required or
+          // already answered, leave the rest one tap away under its own
+          // heading — see `FeatureGroupCollapse`.
+          groupCollapse="auto"
+        />
+      )}
+    </div>
+  );
+
+  // Where the "take me to it" control aims. A feature answers at its own
+  // control id; everything else at the composer's.
+  const missing = bag.firstUnsatisfied;
+  const missingAnchor =
+    missing === undefined
+      ? undefined
+      : props.features.some((feature) => feature.slug === missing)
+        ? featureControlId(missing)
+        : composerFieldId(missing);
   // Whether an unfilled slot draws its named placeholder — and therefore
   // whether the field it belongs to exists at all.
   const namedSlots = props.slotVisibility === "visible" || isDevBuild();
@@ -459,6 +640,7 @@ export function ListingComposerPage(
             named={namedSlots}
             status={errorOf(CATEGORY_FIELD)}
             testId="listings-composer-category"
+            anchorId={composerFieldId(CATEGORY_FIELD)}
             control={props.renderCategoryPicker?.({
               value: bag.values.categoryId,
               setCategory: bag.setCategory,
@@ -481,6 +663,7 @@ export function ListingComposerPage(
             {...errorOf(TITLE_FIELD)}
           >
             <Input
+              id={composerFieldId(TITLE_FIELD)}
               value={bag.values.title}
               aria-label={t(LISTINGS_I18N_KEYS.composeTitleLabel)}
               data-testid="listings-composer-title"
@@ -496,6 +679,7 @@ export function ListingComposerPage(
             {...errorOf(DESCRIPTION_FIELD)}
           >
             <Input.TextArea
+              id={composerFieldId(DESCRIPTION_FIELD)}
               rows={5}
               value={bag.values.description}
               aria-label={t(LISTINGS_I18N_KEYS.composeDescriptionLabel)}
@@ -518,6 +702,7 @@ export function ListingComposerPage(
             {...errorOf(PRICE_FIELD)}
           >
             <Input
+              id={composerFieldId(PRICE_FIELD)}
               inputMode="decimal"
               value={bag.values.price}
               {...(props.renderCurrencyPicker === undefined
@@ -538,6 +723,7 @@ export function ListingComposerPage(
             named={namedSlots}
             status={{}}
             testId="listings-composer-currency"
+            anchorId={composerFieldId("currency")}
             control={props.renderCurrencyPicker?.({
               value: bag.values.currency,
               setCurrency: (code) => {
@@ -562,6 +748,7 @@ export function ListingComposerPage(
             named={namedSlots}
             status={errorOf(LOCATION_FIELD)}
             testId="listings-composer-location"
+            anchorId={composerFieldId(LOCATION_FIELD)}
             control={
               props.renderLocationPicker !== undefined ? (
                 <div data-testid="listings-composer-location-slot">
@@ -608,9 +795,11 @@ export function ListingComposerPage(
               <Typography.Title level={5}>
                 {t(LISTINGS_I18N_KEYS.composePhotos)}
               </Typography.Title>
-              {props.gallerySlot ?? (
-                <SlotPlaceholder name="gallerySlot" visibility="visible" />
-              )}
+              <div id={composerFieldId(IMAGES_FIELD)}>
+                {props.gallerySlot ?? (
+                  <SlotPlaceholder name="gallerySlot" visibility="visible" />
+                )}
+              </div>
               {bag.fieldErrors[IMAGES_FIELD] ? (
                 <Typography.Text type="danger" data-testid="listings-composer-images-error">
                   {describe(bag.fieldErrors[IMAGES_FIELD]).message}
@@ -619,33 +808,9 @@ export function ListingComposerPage(
             </>
           ) : null}
 
-          <Divider />
-
-          <Typography.Title level={5}>
-            {t(LISTINGS_I18N_KEYS.composeDetails)}
-          </Typography.Title>
-          {props.featuresError !== undefined ? (
-            <ErrorAlert
-              testId="listings-composer-features-failed"
-              message={t(LISTINGS_I18N_KEYS.composeDetailsFailed)}
-            />
-          ) : props.featuresLoading === true ? (
-            <Typography.Text type="secondary" data-testid="listings-composer-features-loading">
-              {t(LISTINGS_I18N_KEYS.composeDetailsLoading)}
-            </Typography.Text>
-          ) : props.features.length === 0 ? (
-            <Typography.Text type="secondary" data-testid="listings-composer-features-empty">
-              {t(LISTINGS_I18N_KEYS.composeDetailsEmpty)}
-            </Typography.Text>
-          ) : (
-            <FeatureFields
-              features={props.features}
-              values={bag.values.features}
-              errors={bag.fieldErrors}
-              disabled={bag.publishing}
-              onChange={bag.setFeature}
-            />
-          )}
+          {/* The category's own questions, after the five the seller came to
+              answer. See the header on why this is one order and not two. */}
+          {details}
 
           <Divider />
 
@@ -749,6 +914,30 @@ export function ListingComposerPage(
             {bag.publishing ? t(LISTINGS_I18N_KEYS.composePublishing) : publishLabel}
           </GatedButton>
 
+          {/* A count with nowhere to go is a dead end: "10 required details
+              are still empty" is printed by the gate above with not one of
+              them on screen, because the attribute region starts below the
+              fold. This is the way to the first of them — a real button, with
+              its own accessible name, and not a click handler stuck on the
+              sentence (which announces as text and cannot be tabbed to). It
+              appears only while the gate is closed, so it never stands under
+              a button that is ready to press. */}
+          {!bag.publishGate.available && missingAnchor !== undefined ? (
+            <Button
+              type="link"
+              size="small"
+              style={{ paddingInline: 0 }}
+              data-testid="listings-composer-goto-missing"
+              data-analytics="none"
+              data-analytics-reason="navigation within the page — the host app wraps business actions with its own tracked()"
+              onClick={() => {
+                revealField(missingAnchor);
+              }}
+            >
+              {t(LISTINGS_I18N_KEYS.composeShowFirstMissing)}
+            </Button>
+          ) : null}
+
           <Flex gap={spacing[3]} wrap align="flex-start">
             <GatedButton
               gate={bag.saveGate}

package/src/default/ListingDetailPane.tsx

@@ -59,7 +59,7 @@ import { HeartIcon } from "./icons.js";
 import { ListingPhoto } from "./ListingPhoto.js";
 import { ListingPrice } from "./ListingPrice.js";
 import { ListingStatusBlock } from "./StatusTags.js";
-import type { ThemeModeProp } from "./types.js";
+import type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";
 
 /** The reading measure of the page body. A detail page is prose plus a spec
  * table; past this it stops being one column and starts being a stripe across
@@ -73,7 +73,9 @@ export const DETAIL_MEASURE = "60rem";
  * postage stamp on the other. */
 export const DETAIL_PHOTO_MIN = "14rem";
 
-export interface ListingDetailPaneProps extends ThemeModeProp {
+export interface ListingDetailPaneProps
+  extends ThemeModeProp,
+    CategoryFeaturesProp {
   readonly id: number;
   /** The reader's own uuid, when the host knows it. Enables the owner view —
    * the only place the moderation axis is shown, because it is the only
@@ -98,10 +100,12 @@ export interface ListingDetailPaneProps extends ThemeModeProp {
 export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const t = useT();
   const { locale } = useI18n();
-  const bag = useListingDetail(
-    props.id,
-    props.viewerId !== undefined ? { viewerId: props.viewerId } : {}
-  );
+  const bag = useListingDetail(props.id, {
+    ...(props.viewerId !== undefined ? { viewerId: props.viewerId } : {}),
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+  });
   const owner = bag.viewerIsOwner === true;
   const actions = useListingActions(props.id, bag.status?.lifecycle.status);
   const editGate = actions.editGate(props.onEdit !== undefined);

package/src/default/ListingSerpCard.tsx

@@ -74,6 +74,7 @@ import {
   featuresDtoFromDaoList,
   featuresFromDaoList,
 } from "../model/features.js";
+import type { FeatureCopySource } from "../model/features.js";
 import { lifecycleCaption } from "../model/status.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { PriceTrendIcon } from "./icons.js";
@@ -86,7 +87,7 @@ import {
 import type { ListingCardOpenProps } from "./ListingCard.js";
 import { LISTING_PHOTO_ASPECT, ListingPhoto } from "./ListingPhoto.js";
 import { ListingPrice } from "./ListingPrice.js";
-import type { ThemeModeProp } from "./types.js";
+import type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";
 
 /**
  * A price that moved, as the ref draws it: the old figure struck through and
@@ -103,7 +104,9 @@ export interface ListingPriceTrend {
   readonly direction: "down" | "up";
 }
 
-export interface ListingSerpCardBaseProps extends ThemeModeProp {
+export interface ListingSerpCardBaseProps
+  extends ThemeModeProp,
+    CategoryFeaturesProp {
   readonly listing: ListingCardData;
   /**
    * The seller's own one-line summary — "Petrol 1.5 (147 hp), robot, front".
@@ -149,7 +152,13 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   const { token } = antdTheme.useToken();
 
   const badgeDaos = asFeatureDaoList(listing.features_badges);
-  const badgeFeatures = featuresFromDaoList(badgeDaos);
+  // See `CategoryFeaturesProp`: the option table a stored `select` does not
+  // carry, when this surface knows which category it is drawing.
+  const copy: FeatureCopySource =
+    props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {};
+  const badgeFeatures = featuresFromDaoList(badgeDaos, copy);
   const badgeValues = featuresDtoFromDaoList(badgeDaos);
   // The fallback spec line when the host derived none: the row's own
   // `features_title` projection, exactly the line `ListingCard` draws.
@@ -315,7 +324,7 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
                     data-testid="listings-serp-specs"
                   >
                     <FeatureBadges
-                      features={featuresFromDaoList(titleDaos).map(
+                      features={featuresFromDaoList(titleDaos, copy).map(
                         (view) => view.feature,
                       )}
                       values={featuresDtoFromDaoList(titleDaos)}

package/src/default/index.ts

@@ -55,7 +55,12 @@ export { FeedGrid, FEED_GRID_COLUMNS } from "./FeedGrid.js";
 export type { FeedGridProps } from "./FeedGrid.js";
 export { ListingDetailPane, DETAIL_MEASURE, DETAIL_PHOTO_MIN } from "./ListingDetailPane.js";
 export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
-export { ListingComposerPage, COMPOSER_MEASURE } from "./ListingComposerPage.js";
+export {
+  ListingComposerPage,
+  COMPOSER_DETAILS_PLACEMENT,
+  COMPOSER_MEASURE,
+  composerFieldId,
+} from "./ListingComposerPage.js";
 export type {
   ListingComposerPageProps,
   ComposerCategorySlot,
@@ -78,4 +83,4 @@ export { ListingPhoto, LISTING_PHOTO_ASPECT } from "./ListingPhoto.js";
 export type { ListingPhotoProps } from "./ListingPhoto.js";
 export { SignInLink } from "./SignInLink.js";
 export type { SignInLinkProps } from "./SignInLink.js";
-export type { ThemeModeProp } from "./types.js";
+export type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";

package/src/default/types.ts

@@ -4,9 +4,31 @@
  */
 export type { FlowError } from "@stapel/core";
 import type { ThemeMode } from "@stapel/tokens-antd";
+import type { FeatureDef } from "@stapel/attributes-react";
 
 /** Every `/default` surface accepts a theme mode; absent means "whatever the
  * host document declares" (`resolveThemeMode()`), never a hardcoded side. */
 export interface ThemeModeProp {
   readonly mode?: ThemeMode;
 }
+
+/**
+ * Every surface that DISPLAYS stored feature values takes this, and it is
+ * optional on all of them.
+ *
+ * A stored `select` carries its chosen values and no option table (the table
+ * lives on the category), so a row written before the label snapshot existed
+ * prints its storage slug — "b-u" where the catalogue holds the copy. A
+ * surface that knows which category it is drawing can hand the category's own
+ * defs over and the copy is repaired; a mixed grid of forty categories knows
+ * no such thing, passes nothing, and renders exactly what it renders today.
+ *
+ * The precedence between these defs and what the row itself stored is
+ * `model/features.ts`' business — see {@link FeatureCopySource}.
+ */
+export interface CategoryFeaturesProp {
+  /** The category's features, as
+   * `GET /categories/api/v1/categories/{id}/features/` answers — the same
+   * array `<ListingComposerPage>` takes. */
+  readonly categoryFeatures?: readonly FeatureDef[];
+}

package/src/headless/ListingComposer.tsx

@@ -40,6 +40,7 @@ import type { ListingDraftValues, ListingLocation } from "../model/draft.js";
 import { asFeatureDaoList } from "../model/features.js";
 import { featuresDtoFromDaoList } from "../model/features.js";
 import {
+  LISTING_FIELD_ORDER,
   envelopeFieldErrors,
   mirrorDraft,
   publishRefusal,
@@ -201,6 +202,17 @@ export interface ListingComposerBag {
   readonly fieldErrors: Readonly<Record<string, FlowError>>;
   /** The server's last publish refusal, unrouted, for a summary line. */
   readonly refusal: PublishRefusal | undefined;
+  /**
+   * The first field the mirror is refusing, in the order the form asks for it
+   * (`LISTING_FIELD_ORDER`, then the category's features in schema order), or
+   * `undefined` when nothing is refused.
+   *
+   * The publish gate can say "10 required details are still empty" while not
+   * one of them is on screen — on a phone the attribute region starts nearly
+   * two viewports below the fold — and a count with nowhere to go is a dead
+   * end. This is what a skin's "take me there" control aims at.
+   */
+  readonly firstUnsatisfied: string | undefined;
   /** Value types this build cannot draw — the fact, from attributes-react. */
   readonly unsupported: readonly string[];
 
@@ -378,6 +390,21 @@ export function useListingComposer(
     return { ...shown, ...envelopeFieldErrors(saveThrown), ...routed };
   }, [showErrors, mirror, refusal, saveThrown]);
 
+  // The order is the FORM's, not the record's — see `LISTING_FIELD_ORDER`.
+  // A key in neither list (a server field with no control of its own) is still
+  // named rather than dropped: something is refusing, and saying which is
+  // better than saying nothing.
+  const firstUnsatisfied: string | undefined = useMemo(() => {
+    const refused = mirror;
+    for (const field of LISTING_FIELD_ORDER) {
+      if (refused[field] !== undefined) return field;
+    }
+    for (const feature of options.features) {
+      if (refused[feature.slug] !== undefined) return feature.slug;
+    }
+    return Object.keys(refused)[0];
+  }, [mirror, options.features]);
+
   const listingState: LoadState<ListingDetailData> | undefined =
     options.listingId === undefined
       ? undefined
@@ -571,6 +598,7 @@ export function useListingComposer(
     mirror,
     fieldErrors,
     refusal,
+    firstUnsatisfied,
     unsupported,
 
     saveGate,

package/src/headless/ListingDetail.tsx

@@ -11,6 +11,7 @@ import {
 } from "@stapel/core";
 import type { ActionAvailability, LoadState } from "@stapel/core";
 import type {
+  FeatureDef,
   ListingDetail as ListingDetailData,
   ListingFeatureView,
   ListingStatusInfo,
@@ -18,6 +19,7 @@ import type {
 import { useListing, useListingStatus } from "../model/queries.js";
 import { useFavoriteListing } from "../model/mutations.js";
 import { asFeatureDaoList, featuresFromDaoList, unreadableFeatureCount } from "../model/features.js";
+import type { FeatureCopySource } from "../model/features.js";
 import { listingStatusView } from "../model/status.js";
 import type { ListingStatusView } from "../model/status.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
@@ -104,6 +106,19 @@ export interface UseListingDetailOptions {
   /** The reader's own id, when the host knows it — enables `viewerIsOwner`.
    * A uuid string, matching `ListingDetail.owner` / `ListingStatus.owner_id`. */
   readonly viewerId?: string;
+  /**
+   * The listing's category features, when the container has them — the same
+   * `readonly FeatureDef[]` the composer takes, from
+   * `@stapel/categories-react`'s `useCategoryFeatures`.
+   *
+   * A stored `select` carries its chosen VALUES and no option table, so a row
+   * written before labels were snapshotted prints its storage slug (`b-u`)
+   * where the category holds the copy. Handing the category's defs in repairs
+   * that; handing nothing in leaves every rendered value exactly as it is
+   * today. Which definition wins over which is `model/features.ts`' business —
+   * this is only the wire it travels on.
+   */
+  readonly categoryFeatures?: readonly FeatureDef[];
 }
 
 export function useListingDetail(
@@ -166,17 +181,25 @@ export function useListingDetail(
       ? undefined
       : owner === options.viewerId;
 
+  // One object, rebuilt only when the defs themselves change, so the three
+  // projections below keep their memo across renders that touched neither.
+  const categoryFeatures = options.categoryFeatures;
+  const copy: FeatureCopySource = useMemo(
+    () => (categoryFeatures !== undefined ? { categoryFeatures } : {}),
+    [categoryFeatures]
+  );
+
   const features = useMemo(
-    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features)),
-    [detail.data]
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features), copy),
+    [detail.data, copy]
   );
   const titleFeatures = useMemo(
-    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_title)),
-    [detail.data]
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_title), copy),
+    [detail.data, copy]
   );
   const badgeFeatures = useMemo(
-    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_badges)),
-    [detail.data]
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_badges), copy),
+    [detail.data, copy]
   );
 
   const isFavorited = detail.data?.is_favorited ?? undefined;
@@ -228,11 +251,15 @@ export function useListingDetail(
 export function ListingDetail(props: {
   id: number;
   viewerId?: string;
+  /** See {@link UseListingDetailOptions.categoryFeatures}. */
+  categoryFeatures?: readonly FeatureDef[];
   children: (bag: ListingDetailBag) => ReactNode;
 }): ReactElement {
-  const bag = useListingDetail(
-    props.id,
-    props.viewerId !== undefined ? { viewerId: props.viewerId } : {}
-  );
+  const bag = useListingDetail(props.id, {
+    ...(props.viewerId !== undefined ? { viewerId: props.viewerId } : {}),
+    ...(props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {}),
+  });
   return <>{props.children(bag)}</>;
 }

package/src/i18n/es.ts

@@ -130,6 +130,8 @@ export const listingsI18nBundleEs: I18nDictionary = {
     "Un anuncio admite como mucho {max} fotos",
   "listings.compose.details": "Detalles",
   "listings.compose.details_loading": "Cargando lo que pide esta categoría…",
+  "listings.compose.details_no_category":
+    "Elige primero una categoría: aquí aparecerá lo que pide.",
   "listings.compose.details_failed":
     "No pudimos cargar lo que pide esta categoría",
   "listings.compose.details_empty": "Esta categoría no pide más detalles",
@@ -159,6 +161,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.compose.blocked.busy":
     "Un momento — el último cambio se está guardando",
   "listings.compose.blocked.incomplete": "Faltan {count} datos obligatorios",
+  "listings.compose.show_first_missing": "Ir al primer campo sin completar",
   "listings.compose.blocked.mirror": "Corrige primero los campos marcados",
   "listings.compose.blocked.details_unavailable":
     "No pudimos cargar lo que pide esta categoría, así que no podemos revisar el formulario",
@@ -218,7 +221,9 @@ export const listingsI18nBundleEs: I18nDictionary = {
 
   "listings.nav.detail": "Anuncio",
   "listings.nav.compose": "Poner un anuncio",
+  "listings.nav.compose.short": "Poner",
   "listings.nav.mine": "Mis anuncios",
+  "listings.nav.mine.short": "Míos",
   "listings.nav.favorites": "Favoritos",
 };