@stapel/listings-react 0.10.0 → 0.12.0

package/dist/nav/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAyCA;;iEAEiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,EAAE,EAAE,iBAAiB;QACrB,QAAQ,EAAE,qBAAqB;QAC/B,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,SAAS,EAAE,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC9D,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,QAAQ,EAAE,sBAAsB;QAChC,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACvB,SAAS,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE;QAChE,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,qEAAqE;QACrE,EAAE,EAAE,eAAe;QACnB,QAAQ,EAAE,mBAAmB;QAC7B,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAC3B,SAAS,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC3D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,QAAQ,EAAE,wBAAwB;QAClC,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;QAC5B,SAAS,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE;QAC1D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;CACF,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAyCA;;iEAEiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,EAAE,EAAE,iBAAiB;QACrB,QAAQ,EAAE,qBAAqB;QAC/B,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,SAAS,EAAE,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC9D,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,QAAQ,EAAE,sBAAsB;QAChC,aAAa,EAAE,4BAA4B;QAC3C,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACvB,SAAS,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE;QAChE,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,qEAAqE;QACrE,EAAE,EAAE,eAAe;QACnB,QAAQ,EAAE,mBAAmB;QAC7B,aAAa,EAAE,yBAAyB;QACxC,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAC3B,SAAS,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC3D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,QAAQ,EAAE,wBAAwB;QAClC,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;QAC5B,SAAS,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE;QAC1D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;CACF,CAAC"}

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/listings-react 0.10.0
+# @stapel/listings-react 0.12.0
 
 Headless React flow pair for stapel-listings (contract >=0.10 <0.11) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/listings-react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "backend": {
     "module": "stapel-listings",
     "contract": ">=0.10 <0.11"
@@ -921,6 +921,7 @@
     "listings.compose.details_empty",
     "listings.compose.details_failed",
     "listings.compose.details_loading",
+    "listings.compose.details_no_category",
     "listings.compose.edit_title",
     "listings.compose.geo_incomplete",
     "listings.compose.invalid_summary",
@@ -938,6 +939,7 @@
     "listings.compose.save",
     "listings.compose.saved",
     "listings.compose.saving",
+    "listings.compose.show_first_missing",
     "listings.compose.stock",
     "listings.compose.title_label",
     "listings.compose.title_too_long",
@@ -998,9 +1000,11 @@
     "listings.moderation.rejected",
     "listings.moderation.rejected_still_live",
     "listings.nav.compose",
+    "listings.nav.compose.short",
     "listings.nav.detail",
     "listings.nav.favorites",
     "listings.nav.mine",
+    "listings.nav.mine.short",
     "listings.page.indicator",
     "listings.page.next",
     "listings.page.prev",
@@ -1035,6 +1039,7 @@
       "LISTING_PUBLISH_VALIDATION_FAILED",
       "LISTING_STATUSES",
       "LISTING_TRANSITIONS",
+      "LOCATION_FIELD",
       "ListingComposer",
       "ListingDetail",
       "ListingsProvider",
@@ -1058,6 +1063,7 @@
       "draftValuesFromWire",
       "droppedFeatureSlugs",
       "emptyDraftValues",
+      "envelopeFieldErrors",
       "explainListingsError",
       "failedResults",
       "featureFromDao",
@@ -1121,6 +1127,7 @@
       "FavoriteToggleResponse",
       "FavoritesBag",
       "FeatureConfig",
+      "FeatureCopySource",
       "FeatureDef",
       "FeatureValueDto",
       "FlowEndpoint",

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/listings-react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "entries": [
     {
       "id": "listings.detail",
@@ -24,6 +24,7 @@
     {
       "id": "listings.compose",
       "labelKey": "listings.nav.compose",
+      "shortLabelKey": "listings.nav.compose.short",
       "icon": "PlusOutlined",
       "route": {
         "path": "/new"
@@ -43,6 +44,7 @@
     {
       "id": "listings.mine",
       "labelKey": "listings.nav.mine",
+      "shortLabelKey": "listings.nav.mine.short",
       "icon": "ProfileOutlined",
       "route": {
         "path": "listings"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/listings-react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Headless React pair for stapel-listings: a typed client over the draft twin, the composer that turns a category schema into a submittable listing, and the owner's dashboard. Two independent axes are rendered as two — lifecycle `status` decides visibility and `moderation_status` decides nothing about it, so an edit to a live listing stays live and says 'under review' instead of vanishing. Feature values are drawn and mirrored by @stapel/attributes-react; photos arrive as an injected upload bag whose `refs` ARE `images_draft` and whose `settled` gates the submit; a publish refusal is routed onto the control that caused it by slug. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
   "license": "MIT",
   "repository": {
@@ -48,9 +48,9 @@
   ],
   "size-limit": [
     {
-      "name": "index — the headless pair (client + status axes + draft model + hooks): no antd. Raised 11 -> 11.5 KB for the elevation gate (useElevatableMandateGate + core's useElevation): the anonymous arm can now mint an identity for a named action instead of refusing, and that is a state hook the gate did not previously carry",
+      "name": "index — the headless pair (client + status axes + draft model + hooks): no antd. Raised 11 -> 12 KB for the elevation gate (useElevatableMandateGate + core's useElevation): the anonymous arm can now mint an identity for a named action instead of refusing, and that is a state hook the gate did not previously carry. Raised 11.5 -> 12 KB for envelopeFieldErrors and its API-field -> control table: a save-draft/create 400 names its field in the envelope rather than in a publish batch, and without the table the refusal had nowhere to land — which is how one over-precise coordinate painted two unreadable banners and left every control clean. Thirty-six bytes of routing table is what a legible refusal costs. Raised 12 -> 13 KB for two seams the mobile wave needed in the HEADLESS half: the category-feature copy source in model/features.ts (the option table a stored select does not carry, so a published listing prints \"Second-hand\" and not \"b-u\"), and firstUnsatisfied (the field a \"10 required details are still empty\" count actually points at, in the order the form asks). Both are model, not skin: a headless host renders its own controls and needs the same two answers",
       "path": "dist/index.js",
-      "limit": "11.5 KB"
+      "limit": "13 KB"
     },
     {
       "name": "default — the antd skin (three cards, detail, composer, dashboard, the named slots and the delete confirmation) must stay out of the main bundle. Raised 17 -> 19 KB for the mobile wave: <ListingSerpCard> (photo strip + price-first block + action rail), <ListingFeedCard> and <FeedGrid> are two more card surfaces on the same shared target/favourite/photo parts, not three copies of one",
@@ -102,13 +102,13 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.5.0",
-    "@stapel/core": "^0.20.0",
-    "@stapel/currencies-react": "^0.2.0",
+    "@stapel/attributes-react": "^0.6.0",
+    "@stapel/core": "^0.22.0",
+    "@stapel/currencies-react": "^0.3.0",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.6.0",
-    "@stapel/tokens-antd": "^0.9.0"
+    "@stapel/tokens-antd": "^0.11.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/listings-react",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "defined": [],
   "flows": []
 }

package/src/api/types.ts

@@ -176,6 +176,16 @@ export interface ListingFeatureDao {
    * can lack it and a JSONField will pass that through. */
   readonly type?: ListingFeatureType;
   readonly value?: unknown;
+  /**
+   * The write-time LABEL SNAPSHOT: the copy each entry of `value` had when the
+   * listing was stored, positionally aligned with it, one entry per value.
+   * `ref_select`/`ref_hierarchical_select` have always carried it (their codes
+   * name vocabulary terms no display package can reach) and `select` carries
+   * it from the release that snapshots option copy — so it is OPTIONAL, and a
+   * row stored before that one has no key at all. `model/features.ts` reads
+   * it, and says what a row without it falls back to.
+   */
+  readonly labels?: readonly string[];
   /** Display name or translation key; falls back to the slug. */
   readonly name?: string | null;
   readonly order?: number | null;

package/src/default/ListingCard.tsx

@@ -82,6 +82,7 @@ import { spacing } from "@stapel/tokens";
 import { FeatureBadges } from "@stapel/attributes-react/default";
 import type { ListingCard as ListingCardData } from "../api/types.js";
 import { asFeatureDaoList, featuresDtoFromDaoList, featuresFromDaoList } from "../model/features.js";
+import type { FeatureCopySource } from "../model/features.js";
 import { lifecycleCaption } from "../model/status.js";
 import { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
@@ -89,7 +90,7 @@ import { HeartIcon } from "./icons.js";
 import { SignInLink } from "./SignInLink.js";
 import { ListingPhoto } from "./ListingPhoto.js";
 import { ListingPrice } from "./ListingPrice.js";
-import type { ThemeModeProp } from "./types.js";
+import type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";
 
 /**
  * How the card opens — ONE of three, and the type says so.
@@ -195,7 +196,10 @@ const BUTTON_TARGET_STYLE: CSSProperties = {
   cursor: "pointer",
 };
 
-export interface ListingCardBaseProps extends ThemeModeProp, SignInCtaProp {
+export interface ListingCardBaseProps
+  extends ThemeModeProp,
+    SignInCtaProp,
+    CategoryFeaturesProp {
   readonly listing: ListingCardData;
   /** See {@link ListingCardBlockedReason}. Default `"text"`. */
   readonly blockedReason?: ListingCardBlockedReason;
@@ -309,7 +313,14 @@ export function ListingCard(props: ListingCardProps): ReactElement {
   const { token } = antdTheme.useToken();
 
   const badgeDaos = asFeatureDaoList(listing.features_badges);
-  const badgeFeatures = featuresFromDaoList(badgeDaos);
+  // The category's own option table, when the surface has it: a stored
+  // `select` carries no table of its own, so without this a badge prints the
+  // storage slug. Absent on a mixed grid, which is why it is optional.
+  const copy: FeatureCopySource =
+    props.categoryFeatures !== undefined
+      ? { categoryFeatures: props.categoryFeatures }
+      : {};
+  const badgeFeatures = featuresFromDaoList(badgeDaos, copy);
   const badgeValues = featuresDtoFromDaoList(badgeDaos);
   const titleDaos = asFeatureDaoList(listing.features_title);
 
@@ -370,7 +381,9 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         {titleDaos.length > 0 ? (
           <Typography.Text type="secondary" ellipsis>
             <FeatureBadges
-              features={featuresFromDaoList(titleDaos).map((view) => view.feature)}
+              features={featuresFromDaoList(titleDaos, copy).map(
+                (view) => view.feature
+              )}
               values={featuresDtoFromDaoList(titleDaos)}
             />
           </Typography.Text>

package/src/default/ListingComposerPage.tsx

@@ -50,6 +50,22 @@
  * do not import each other; the container is the seam. A library that picked
  * one would pick it for every host.
  *
+ * ── On a narrow form the CHARACTERISTICS come before the photos ────────────
+ *
+ * The details of the chosen category are the questions only that category
+ * asks, and they are the reason a category is chosen at all. On a wide form
+ * they can sit after the photos, because the whole form is one screen. On a
+ * 390px one they cannot: measured on a live classified deployment, choosing
+ * Mobile phones grew the page to 7292px and put the first attribute control at
+ * y=1596 — nearly two viewports below the fold, behind a ~700px photo dropzone
+ * — while the footer said "10 required details not filled in" with none of
+ * them on screen. So on a narrow form the section moves directly under the
+ * category that produced it, and the photo dropzone follows it.
+ *
+ * The measurement is the FORM's own width (`useElementWidth`, the fleet's one
+ * observer), not the viewport's: a composer is not a viewport, and a viewport
+ * query would call a 360px pane on a desktop "wide".
+ *
  * ── 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
@@ -60,9 +76,11 @@
  * would be told, and `<GatedButton>` renders the reason beside the button —
  * never a grey rectangle, never a hover.
  */
+import { useRef } from "react";
 import type { ComponentType, ReactElement, ReactNode } from "react";
 import {
   Alert,
+  Button,
   Checkbox,
   Divider,
   Flex,
@@ -76,6 +94,7 @@ import {
   GatedButton,
   PaneGate,
   SkinTheme,
+  useElementWidth,
 } from "@stapel/tokens-antd/skin";
 import {
   SlotPlaceholder,
@@ -85,11 +104,12 @@ import {
   useI18n,
   useT,
 } from "@stapel/core";
-import { spacing } from "@stapel/tokens";
+import { breakpoints, spacing } from "@stapel/tokens";
 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";
@@ -98,8 +118,10 @@ import {
   CATEGORY_FIELD,
   DESCRIPTION_FIELD,
   IMAGES_FIELD,
+  LOCATION_FIELD,
   PRICE_FIELD,
   TITLE_FIELD,
+  envelopeFieldErrors,
   failedResults,
 } from "../model/validation.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
@@ -112,6 +134,61 @@ import type { ThemeModeProp } from "./types.js";
  */
 export const COMPOSER_MEASURE = "44rem";
 
+/**
+ * Below this FORM width the composer is a one-thumb column, and the order of
+ * its sections has to change — see {@link ListingComposerPage}'s header on why
+ * the characteristics move up.
+ *
+ * The `tablet` breakpoint, which is what "narrow" means everywhere else in the
+ * skin, measured against the form's OWN width and never the viewport's (§83).
+ * A composer drawn in a 360px settings pane on a 1440px desktop is narrow; a
+ * viewport query would call it wide and bury its questions.
+ */
+export const COMPOSER_STACKED_BELOW: number = breakpoints.tablet;
+
+/**
+ * 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: bring it into view, and focus what
+ * they are meant to answer.
+ *
+ * Both halves are 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;
+  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
@@ -316,22 +393,34 @@ 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>
   );
 }
 
+/** Did this refusal land on a control? Then the control is where it is read. */
+function routedToAControl(thrown: unknown): boolean {
+  return Object.keys(envelopeFieldErrors(thrown)).length > 0;
+}
+
 /** A decimal string → the number a picker works in, or `null`. */
 function toNumber(value: string | null): number | null {
   if (value === null || value.length === 0) return null;
@@ -394,6 +483,76 @@ export function ListingComposerPage(
   );
 
   const LocationPicker = props.locationPicker;
+  // The FORM's width, which is what decides the section order — see the
+  // header. `?? false` because an unmeasured box is not a narrow one (the rule
+  // `useElementWidth` states for every caller): the wide order is the one that
+  // reflows gracefully, so it is what the first frame draws.
+  const form = useRef<HTMLDivElement>(null);
+  const { below } = useElementWidth(form, {
+    thresholds: { stacked: COMPOSER_STACKED_BELOW },
+  });
+  const stacked = below.stacked ?? false;
+
+  /**
+   * 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={stacked ? "after-category" : "after-photos"}
+    >
+      <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}
+        />
+      )}
+    </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();
@@ -444,6 +603,11 @@ export function ListingComposerPage(
           />
         ) : null}
 
+        {/* The measured box is the FORM, so a host that renders this page in
+            a narrow pane gets the narrow order without the viewport agreeing.
+            A plain block wrapper: antd's `Form` forwards its ref to the form
+            INSTANCE, not to a node. */}
+        <div ref={form}>
         <Form layout="vertical" data-testid="listings-composer-form">
           <SlotField
             label={t(LISTINGS_I18N_KEYS.composeCategory)}
@@ -452,6 +616,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,
@@ -469,11 +634,16 @@ export function ListingComposerPage(
             />
           ) : null}
 
+          {/* Narrow: the category's own questions, directly under the choice
+              that produced them and above the photo dropzone. */}
+          {stacked ? details : null}
+
           <Form.Item
             label={t(LISTINGS_I18N_KEYS.composeTitleLabel)}
             {...errorOf(TITLE_FIELD)}
           >
             <Input
+              id={composerFieldId(TITLE_FIELD)}
               value={bag.values.title}
               aria-label={t(LISTINGS_I18N_KEYS.composeTitleLabel)}
               data-testid="listings-composer-title"
@@ -489,6 +659,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)}
@@ -511,6 +682,7 @@ export function ListingComposerPage(
             {...errorOf(PRICE_FIELD)}
           >
             <Input
+              id={composerFieldId(PRICE_FIELD)}
               inputMode="decimal"
               value={bag.values.price}
               {...(props.renderCurrencyPicker === undefined
@@ -531,6 +703,7 @@ export function ListingComposerPage(
             named={namedSlots}
             status={{}}
             testId="listings-composer-currency"
+            anchorId={composerFieldId("currency")}
             control={props.renderCurrencyPicker?.({
               value: bag.values.currency,
               setCurrency: (code) => {
@@ -553,8 +726,9 @@ export function ListingComposerPage(
             extra={t(LISTINGS_I18N_KEYS.composeLocationHelp)}
             slot="locationPicker"
             named={namedSlots}
-            status={errorOf("location")}
+            status={errorOf(LOCATION_FIELD)}
             testId="listings-composer-location"
+            anchorId={composerFieldId(LOCATION_FIELD)}
             control={
               props.renderLocationPicker !== undefined ? (
                 <div data-testid="listings-composer-location-slot">
@@ -601,9 +775,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}
@@ -612,33 +788,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}
-            />
-          )}
+          {/* Wide: the whole form is one screen, so the details keep their
+              place after the photos. */}
+          {stacked ? null : details}
 
           <Divider />
 
@@ -680,6 +832,7 @@ export function ListingComposerPage(
             </Checkbox>
           </Form.Item>
         </Form>
+        </div>
 
         {bag.refusal?.kind === "invalid_draft" ? (
           <ErrorAlert
@@ -690,7 +843,13 @@ export function ListingComposerPage(
           />
         ) : null}
 
-        {bag.refusal?.kind === "error" ? (
+        {/* A refusal that reached a control is READ there, under the field
+            the person can change. Repeating it as a banner — twice, since a
+            publish saves the draft first and both failures are the same 400 —
+            is how one refused coordinate painted two identical "Validation
+            error" plaques and named nothing (blocker C2). The banner is for
+            what has nowhere else to go. */}
+        {bag.refusal?.kind === "error" && !routedToAControl(bag.refusal.error) ? (
           <ErrorAlert
             testId="listings-composer-error"
             error={describe({
@@ -703,7 +862,9 @@ export function ListingComposerPage(
           />
         ) : null}
 
-        {bag.saveError !== undefined && bag.saveError !== null ? (
+        {bag.saveError !== undefined &&
+        bag.saveError !== null &&
+        !routedToAControl(bag.saveError) ? (
           <ErrorAlert
             testId="listings-composer-save-error"
             thrown={bag.saveError}
@@ -734,6 +895,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}