@stapel/listings-react 0.4.0 → 0.8.0

package/src/default/ListingComposerPage.tsx

@@ -1,32 +1,54 @@
 /**
  * `<ListingComposerPage>` — the submission screen.
  *
- * Four contracts meet on this page and each arrives through its own seam, so
+ * Five contracts meet on this page and each arrives through its own seam, so
  * the component can be read top to bottom without knowing any of the other
  * pairs:
  *
  *   category   `renderCategoryPicker` — the container's `<CategoryPickerField>`,
  *                                given `setCategory` to call
+ *   where      `locationPicker`  — the container's `<LocationPickerField>`
+ *                                (`@stapel/geo-react`)
+ *   currency   `renderCurrencyPicker` — whatever vocabulary the deployment sells in
  *   details    `features`      — the schema, drawn by `<FeatureFields>` (L0)
  *   photos     `gallerySlot`   — the container's `<MediaGalleryField bag>`,
  *                                whose bag is handed here as `images`
  *   the draft  this pair
  *
- * ── Why the category slot is a render prop and not a node ──────────────────
+ * ── An unfilled slot is NAMED, never improvised ────────────────────────────
  *
- * It was a node (`categorySlot`), and a node cannot be mounted: the composer's
- * category moves only through `bag.setCategory`, and a `ReactNode` handed in
- * from outside has no way to reach it. There was no `onCategoryChange`either,
- * so a container could neither set the category nor learn it — and `features`,
- * the schema of the chosen category, was therefore unreachable rather than
- * merely withheld. The screen could not be mounted at all (storefront Wave D,
- * named gap G-1).
+ * Every one of those four slots used to degrade into a control this pair could
+ * write on its own, and every one of those controls asked a question no seller
+ * can answer: a numeric category id typed into a text box, a currency CODE
+ * typed into a text box, and — the defect the owner named — two decimal boxes
+ * labelled Latitude and Longitude. A gallery heading with nothing under it was
+ * the same defect with the improvisation left out.
  *
- * `renderCategoryPicker({ value, setCategory })` is the shape
- * `<CategoryPage renderListings>` already uses in the sibling pair, and the
- * controlled pair `category` / `onCategoryChange` is there for the container
- * that holds the id anyway — it must, because the schema read
- * (`useCategoryFeatures(id)`) that fills `features` is keyed by it.
+ * So an unfilled slot renders `<SlotPlaceholder name="…"/>`: a labelled dashed
+ * region in a dev build, nothing at all in production. The rule is the one the
+ * rest of this codebase already lives by — `matchList`'s required empty arm,
+ * `ActionAvailability` with no "disabled for unknown reasons", `LoadState`
+ * refusing to fold failed into empty. A slot was the last place absence could
+ * still be silent, and `stapel/no-silent-slot` now says so at lint time.
+ *
+ * ── …and its LABEL goes with it ────────────────────────────────────────────
+ *
+ * The placeholder is nothing in production — but the `Form.Item` around it
+ * still drew its label, so a production composer with three unfilled slots
+ * rendered three labelled voids: "Category", "Currency", "Where it is" over
+ * empty space, and a "Photos" heading over air. A label is a promise that a
+ * control follows it. {@link SlotField} therefore renders the WHOLE field —
+ * label, help text and control — or nothing at all, and the `Photos` section
+ * does the same with its heading. `slotVisibility` pins the dev view on so a
+ * production-built showcase can still photograph the named placeholders.
+ *
+ * ── Why the pickers are slots and not dependencies ─────────────────────────
+ *
+ * A category tree, a geocoder and a currency vocabulary are all DEPLOYMENT
+ * knowledge, and all three live in sibling L2 pairs
+ * (`@stapel/categories-react`, `@stapel/geo-react`, the host's own). L2 pairs
+ * do not import each other; the container is the seam. A library that picked
+ * one would pick it for every host.
  *
  * ── Every blocked control says which of six reasons it is ──────────────────
  *
@@ -35,29 +57,42 @@
  * category asks for", "this build cannot draw one of these details", "wait
  * for the photos", "fix the highlighted fields" are six different problems
  * with six different next actions. `firstBlock` orders them the way a person
- * would be told, and the reason is rendered beside the button — never left
- * as a grey rectangle.
+ * would be told, and `<GatedButton>` renders the reason beside the button —
+ * never a grey rectangle, never a hover.
  */
-import type { ReactElement, ReactNode } from "react";
+import type { ComponentType, ReactElement, ReactNode } from "react";
 import {
   Alert,
-  Button,
   Checkbox,
   Divider,
   Flex,
   Form,
   Input,
   InputNumber,
-  Space,
   Typography,
 } from "antd";
-import { useDescribeFlowError, useT } from "@stapel/core";
+import {
+  ErrorAlert,
+  GatedButton,
+  PaneGate,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
+import {
+  SlotPlaceholder,
+  actionAvailable,
+  isDevBuild,
+  useDescribeFlowError,
+  useI18n,
+  useT,
+} from "@stapel/core";
+import { spacing } from "@stapel/tokens";
 import type { FeatureDef } from "@stapel/attributes-react";
 import {
   BUILTIN_VALUE_EDITOR_TYPES,
   FeatureFields,
 } from "@stapel/attributes-react/default";
 import { useListingComposer } from "../headless/ListingComposer.js";
+import type { ListingLocation } from "../model/draft.js";
 import type { ListingImagesBag } from "../headless/ListingComposer.js";
 import {
   CATEGORY_FIELD,
@@ -68,10 +103,15 @@ import {
   failedResults,
 } from "../model/validation.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import { ErrorAlert } from "./ErrorAlert.js";
-import { ListingsSkinTheme } from "./theme.js";
 import type { ThemeModeProp } from "./types.js";
 
+/**
+ * A form is read in one column, and a column has a width past which the eye
+ * loses the line — the reason a 2560px pane once rendered a 1640px Title box.
+ * A measure, not a pixel guess: `ch` scales with the type the theme is set to.
+ */
+export const COMPOSER_MEASURE = "44rem";
+
 /**
  * What `renderCategoryPicker` is handed: the current category and the ONLY
  * function that changes it. Same shape as any other bag in this monorepo — the
@@ -85,6 +125,96 @@ export interface ComposerCategorySlot {
   readonly setCategory: (categoryId: string) => void;
 }
 
+/**
+ * What `renderCurrencyPicker` is handed: the code the draft carries and the
+ * one function that changes it.
+ *
+ * The vocabulary is not this pair's: `Listing.currency` is a free
+ * `maxLength: 8` string on the wire (stapel-listings has no currency enum —
+ * the list lives in stapel-currencies), so the pair holds a DEFAULT from
+ * `createListingsRuntime` and asks the container for a chooser. Unfilled, the
+ * price field simply states which currency it is in.
+ */
+export interface ComposerCurrencySlot {
+  /** ISO-4217-ish code, e.g. `"RUB"`. Never empty — the runtime's default. */
+  readonly value: string;
+  readonly setCurrency: (code: string) => void;
+}
+
+/**
+ * What a location picker component is handed — the contract
+ * `@stapel/geo-react`'s `<LocationPickerField>` was built to fill.
+ *
+ * `{ value, onChange }`, and `value` is the pin plus the address a resolver
+ * found for it. `lat`/`lon` are NUMBERS here (a picker works in numbers) while
+ * the draft keeps decimal STRINGS, because a float round-trips `55.796100`
+ * into `55.7961` and changes what was submitted; the conversion happens in
+ * this component, once, at the seam.
+ *
+ * Geo-react's own props are `value?: LatLon` and
+ * `onChange?: (picked: PickedLocation) => void`, so the adapter a container
+ * writes is three lines and no state:
+ *
+ * ```tsx
+ * import { LocationPickerField } from "@stapel/geo-react/default";
+ *
+ * <ListingComposerPage
+ *   locationPicker={({ value, onChange }) => (
+ *     <LocationPickerField
+ *       {...(value.lat !== null && value.lon !== null
+ *         ? { value: { lat: value.lat, lon: value.lon } }
+ *         : {})}
+ *       onChange={(picked) => {
+ *         onChange({ lat: picked.point.lat, lon: picked.point.lon,
+ *                    address: picked.address ?? undefined });
+ *       }}
+ *     />
+ *   )}
+ * />
+ * ```
+ *
+ * `geohash` is absent from this contract on purpose: since stapel-listings
+ * 0.7.1 the server computes it from the coordinates and ignores anything sent
+ * in the body, so a picker that has one has nowhere to put it and no reason
+ * to try (`model/draft.ts`).
+ */
+export interface ComposerLocationValue {
+  /** Decimal degrees, or `null` when no place has been chosen yet. */
+  readonly lat: number | null;
+  readonly lon: number | null;
+  /** The one-line label a person reads: "Kazan, Vahitovsky district". */
+  readonly address?: string;
+}
+
+export interface ComposerLocationPickerProps {
+  readonly value: ComposerLocationValue;
+  readonly onChange: (next: ComposerLocationValue) => void;
+}
+
+/**
+ * The lower-level location seam: the WHOLE draft composite, and the `save`
+ * the plain fields call on blur.
+ *
+ * Kept beside {@link ComposerLocationPickerProps} for a host whose picker
+ * also resolves a `location_id` out of its own place directory — the id is
+ * this pair's wire field and no generic picker knows about it. A container
+ * that only has a pin and an address wants `locationPicker` instead.
+ */
+export interface ComposerLocationSlot {
+  /** The location the draft currently carries. */
+  readonly value: ListingLocation;
+  /** Write the whole composite. `geohash` is read-only on the wire (0.7.1) —
+   * whatever is written here is kept for display and never sent. */
+  readonly setLocation: (location: ListingLocation) => void;
+  /**
+   * Persist the draft now. The plain fields save on blur, and a picker has no
+   * blur to speak of: choosing a suggestion IS the commit, so the slot is
+   * handed the same `save` those fields call rather than being left to hope
+   * the next unrelated blur carries its value.
+   */
+  readonly save: () => void;
+}
+
 export interface ListingComposerPageProps extends ThemeModeProp {
   /** Editing an existing listing; absent for a new one. */
   readonly listingId?: number;
@@ -105,6 +235,9 @@ export interface ListingComposerPageProps extends ThemeModeProp {
    *   />
    * )}
    * ```
+   *
+   * Unfilled: a named placeholder. The composer will NOT ask a person to type
+   * a category id.
    */
   readonly renderCategoryPicker?: (slot: ComposerCategorySlot) => ReactNode;
   /**
@@ -115,28 +248,97 @@ export interface ListingComposerPageProps extends ThemeModeProp {
   /** Called whenever the category changes, controlled or not. */
   readonly onCategoryChange?: (categoryId: string) => void;
   /**
-   * @deprecated A node cannot reach `setCategory`, so a picker rendered into
-   * this slot could never tell the composer what was chosen. Use
-   * `renderCategoryPicker` (or the controlled `category` /
-   * `onCategoryChange` pair). Still rendered, so nothing that passed it breaks.
+   * The currency chooser. Unfilled, the price field states the deployment's
+   * currency and nothing asks the seller to type a code.
+   */
+  readonly renderCurrencyPicker?: (slot: ComposerCurrencySlot) => ReactNode;
+  /**
+   * WHERE the thing is, asked the host's way — the slot
+   * `@stapel/geo-react`'s `<LocationPickerField>` fills (see
+   * {@link ComposerLocationPickerProps} for the three-line adapter).
+   *
+   * Unfilled: a named placeholder. The composer will NOT fall back to two
+   * decimal boxes — a seller does not know their latitude, and those boxes
+   * were the only reason `location` was ever left empty on this fleet.
+   */
+  readonly locationPicker?: ComponentType<ComposerLocationPickerProps>;
+  /**
+   * The whole-composite form of the same seam, for a picker that also resolves
+   * this pair's `location_id`. Wins over `locationPicker` when both are given.
    */
-  readonly categorySlot?: ReactNode;
-  /** The photo grid. Its bag is what `images` carries. */
+  readonly renderLocationPicker?: (slot: ComposerLocationSlot) => ReactNode;
+  /** The photo grid — `@stapel/cdn-react`'s `<MediaGalleryField bag>`. Its bag
+   * is what `images` carries. Unfilled: a named placeholder, not a heading
+   * over nothing. */
   readonly gallerySlot?: ReactNode;
   /** `useUploadQueue()`'s bag from `@stapel/cdn-react` — `refs` becomes
    * `images_draft`, `settled` gates the submit. */
   readonly images?: ListingImagesBag;
+  /**
+   * Whether an unfilled slot shows its named placeholder. `"auto"` (default)
+   * follows the build: named in development, the whole field absent in
+   * production. `"visible"` pins it on — for a showcase built in production
+   * mode, which is the only way to photograph an integration defect.
+   */
+  readonly slotVisibility?: "auto" | "visible";
   readonly onPublished?: (listingId: number) => void;
 }
 
+/**
+ * A labelled field whose control comes from a slot — or NOTHING.
+ *
+ * The composer's orphan-field bug in one component: a `Form.Item` renders its
+ * label unconditionally, so an unfilled slot (which is `null` in a production
+ * build) left the label standing over empty space. Here the label and the
+ * control are one decision. `named` says whether the dev placeholder will
+ * draw; when it will not and the host filled nothing, the field is not part of
+ * the form at all.
+ */
+function SlotField(props: {
+  readonly label: string;
+  readonly extra?: string;
+  readonly slot: string;
+  readonly named: boolean;
+  readonly control: ReactNode | undefined;
+  readonly status: { help: ReactNode; validateStatus: "error" } | Record<string, never>;
+  readonly testId: string;
+}): ReactElement | null {
+  const filled = props.control !== undefined;
+  if (!filled && !props.named) return null;
+  return (
+    <Form.Item
+      label={props.label}
+      {...(props.extra !== undefined ? { extra: props.extra } : {})}
+      {...props.status}
+    >
+      <div data-testid={props.testId}>
+        {props.control ?? <SlotPlaceholder name={props.slot} visibility="visible" />}
+      </div>
+    </Form.Item>
+  );
+}
+
+/** 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;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
 export function ListingComposerPage(
   props: ListingComposerPageProps
 ): ReactElement {
   const t = useT();
+  const { locale } = useI18n();
   const describe = useDescribeFlowError();
   const bag = useListingComposer({
     ...(props.listingId !== undefined ? { listingId: props.listingId } : {}),
     features: props.features,
+    // A new draft carries the language it was WRITTEN in, and the only honest
+    // guess is the locale the composer is being read in. It was left empty and
+    // the server's default decided instead — a Spanish seller filing a listing
+    // stamped `ru` because that is the deployment default (gap L-9).
+    language: locale,
     ...(props.featuresLoading !== undefined
       ? { featuresLoading: props.featuresLoading }
       : {}),
@@ -177,9 +379,23 @@ export function ListingComposerPage(
       : LISTINGS_I18N_KEYS.composePublish
   );
 
+  const LocationPicker = props.locationPicker;
+  // 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();
+
   return (
-    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
-      <Flex vertical gap={16} data-testid="listings-composer" data-stage={bag.stage}>
+    <SkinTheme
+      surface="base"
+      style={{ maxWidth: COMPOSER_MEASURE, padding: spacing[4] }}
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <Flex
+        vertical
+        gap={spacing[4]}
+        data-testid="listings-composer"
+        data-stage={bag.stage}
+      >
         <Typography.Title level={3}>
           {t(
             props.listingId === undefined
@@ -188,7 +404,7 @@ export function ListingComposerPage(
           )}
         </Typography.Title>
 
-        {/* stapel-listings 0.6.1 exposes no read of the `*_draft` twin, so a
+        {/* stapel-listings 0.7.1 exposes no read of the `*_draft` twin, so a
             draft reopened in a new session comes back empty. Saying so beats
             a blank form that looks like lost work. */}
         {bag.draftNotReadable ? (
@@ -196,7 +412,7 @@ export function ListingComposerPage(
             type="warning"
             showIcon
             data-testid="listings-composer-draft-unreadable"
-            message={t(LISTINGS_I18N_KEYS.composeBlockedNoDraft)}
+            title={t(LISTINGS_I18N_KEYS.composeBlockedNoDraft)}
           />
         ) : null}
 
@@ -206,7 +422,7 @@ export function ListingComposerPage(
             showIcon
             data-testid="listings-composer-published"
             data-outcome={bag.outcome}
-            message={t(
+            title={t(
               bag.outcome === "live_edit_under_review"
                 ? LISTINGS_I18N_KEYS.composePublishedLive
                 : LISTINGS_I18N_KEYS.composePublishedFirst
@@ -215,34 +431,25 @@ export function ListingComposerPage(
         ) : null}
 
         <Form layout="vertical" data-testid="listings-composer-form">
-          <Form.Item
+          <SlotField
             label={t(LISTINGS_I18N_KEYS.composeCategory)}
             extra={t(LISTINGS_I18N_KEYS.composeCategoryHelp)}
-            {...errorOf(CATEGORY_FIELD)}
-          >
-            {props.renderCategoryPicker !== undefined
-              ? props.renderCategoryPicker({
-                  value: bag.values.categoryId,
-                  setCategory: bag.setCategory,
-                })
-              : (props.categorySlot ?? (
-                  <Input
-                    value={bag.values.categoryId}
-                    aria-label={t(LISTINGS_I18N_KEYS.composeCategory)}
-                    data-testid="listings-composer-category"
-                    onChange={(event) => {
-                      bag.setCategory(event.target.value);
-                    }}
-                  />
-                ))}
-          </Form.Item>
+            slot="renderCategoryPicker"
+            named={namedSlots}
+            status={errorOf(CATEGORY_FIELD)}
+            testId="listings-composer-category"
+            control={props.renderCategoryPicker?.({
+              value: bag.values.categoryId,
+              setCategory: bag.setCategory,
+            })}
+          />
 
           {bag.droppedOnCategoryChange.length > 0 ? (
             <Alert
               type="info"
               showIcon
               data-testid="listings-composer-dropped"
-              message={t(LISTINGS_I18N_KEYS.composeCategoryChangedDropped, {
+              title={t(LISTINGS_I18N_KEYS.composeCategoryChangedDropped, {
                 count: bag.droppedOnCategoryChange.length,
               })}
             />
@@ -279,106 +486,116 @@ export function ListingComposerPage(
             />
           </Form.Item>
 
-          <Space align="start" wrap>
-            <Form.Item
-              label={t(LISTINGS_I18N_KEYS.composePriceLabel)}
-              {...errorOf(PRICE_FIELD)}
-            >
-              <Input
-                inputMode="decimal"
-                value={bag.values.price}
-                aria-label={t(LISTINGS_I18N_KEYS.composePriceLabel)}
-                data-testid="listings-composer-price"
-                onChange={(event) => {
-                  bag.setValue("price", event.target.value);
-                }}
-                onBlur={bag.save}
-              />
-            </Form.Item>
-
-            <Form.Item label={t(LISTINGS_I18N_KEYS.composeCurrencyLabel)}>
-              <Input
-                value={bag.values.currency}
-                aria-label={t(LISTINGS_I18N_KEYS.composeCurrencyLabel)}
-                data-testid="listings-composer-currency"
-                onChange={(event) => {
-                  bag.setValue("currency", event.target.value);
-                }}
-                onBlur={bag.save}
-              />
-            </Form.Item>
-          </Space>
-
-          <Form.Item label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}>
+          {/* Price and currency are ONE question, asked ONCE. The currency is
+              not a text box: the vocabulary is the deployment's
+              (stapel-currencies). With no chooser the code rides along as the
+              field's addon so the price still says what it is in; with one,
+              the addon would be a second currency control saying the same
+              thing beside the first. */}
+          <Form.Item
+            label={t(LISTINGS_I18N_KEYS.composePriceLabel)}
+            {...errorOf(PRICE_FIELD)}
+          >
             <Input
-              value={bag.values.location.locationLabel}
-              aria-label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}
-              data-testid="listings-composer-location"
+              inputMode="decimal"
+              value={bag.values.price}
+              {...(props.renderCurrencyPicker === undefined
+                ? { addonAfter: bag.values.currency }
+                : {})}
+              aria-label={t(LISTINGS_I18N_KEYS.composePriceLabel)}
+              data-testid="listings-composer-price"
               onChange={(event) => {
-                bag.setLocation({
-                  ...bag.values.location,
-                  locationLabel: event.target.value,
-                });
+                bag.setValue("price", event.target.value);
               }}
               onBlur={bag.save}
             />
           </Form.Item>
 
-          {/* Latitude and longitude are ONE value: half a coordinate points
-              nowhere, and the mirror refuses it under `location`. `geohash`
-              is not typed here at all — it comes from whatever resolved the
-              place, because a geohash computed at a precision of our own
-              choosing would bucket the pin somewhere the indexer does not
-              expect (model/draft.ts). */}
-          <Space align="start" wrap>
-            <Form.Item
-              label={t(LISTINGS_I18N_KEYS.composeLatLabel)}
-              {...(bag.fieldErrors["location"] ? { validateStatus: "error" as const } : {})}
-            >
-              <Input
-                inputMode="decimal"
-                value={bag.values.location.lat ?? ""}
-                aria-label={t(LISTINGS_I18N_KEYS.composeLatLabel)}
-                data-testid="listings-composer-lat"
-                onChange={(event) => {
-                  bag.setLocation({
-                    ...bag.values.location,
-                    lat: event.target.value.length > 0 ? event.target.value : null,
-                  });
-                }}
-                onBlur={bag.save}
-              />
-            </Form.Item>
-            <Form.Item
-              label={t(LISTINGS_I18N_KEYS.composeLonLabel)}
-              {...errorOf("location")}
-            >
-              <Input
-                inputMode="decimal"
-                value={bag.values.location.lon ?? ""}
-                aria-label={t(LISTINGS_I18N_KEYS.composeLonLabel)}
-                data-testid="listings-composer-lon"
-                onChange={(event) => {
-                  bag.setLocation({
-                    ...bag.values.location,
-                    lon: event.target.value.length > 0 ? event.target.value : null,
-                  });
-                }}
-                onBlur={bag.save}
-              />
-            </Form.Item>
-          </Space>
+          <SlotField
+            label={t(LISTINGS_I18N_KEYS.composeCurrencyLabel)}
+            slot="renderCurrencyPicker"
+            named={namedSlots}
+            status={{}}
+            testId="listings-composer-currency"
+            control={props.renderCurrencyPicker?.({
+              value: bag.values.currency,
+              setCurrency: (code) => {
+                bag.setValue("currency", code);
+                bag.saveSoon();
+              },
+            })}
+          />
 
-          <Divider />
+          {/* WHERE, asked once, by whoever can resolve places.
+              A seller does not know their latitude — two decimal boxes are a
+              question no advert-poster on any marketplace has ever been
+              asked. This pair cannot ask for an ADDRESS on its own either:
+              that needs a geocoder, and a geocoder is a deployment's
+              (`@stapel/geo-react` over stapel-geo, on this fleet). So the
+              question is a slot, and an unfilled slot says its own name
+              instead of improvising a control nobody can use. */}
+          <SlotField
+            label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}
+            extra={t(LISTINGS_I18N_KEYS.composeLocationHelp)}
+            slot="locationPicker"
+            named={namedSlots}
+            status={errorOf("location")}
+            testId="listings-composer-location"
+            control={
+              props.renderLocationPicker !== undefined ? (
+                <div data-testid="listings-composer-location-slot">
+                  {props.renderLocationPicker({
+                    value: bag.values.location,
+                    setLocation: (location) => {
+                      bag.setLocation(location);
+                    },
+                    save: bag.saveSoon,
+                  })}
+                </div>
+              ) : LocationPicker !== undefined ? (
+                <div data-testid="listings-composer-location-slot">
+                  <LocationPicker
+                    value={{
+                      lat: toNumber(bag.values.location.lat),
+                      lon: toNumber(bag.values.location.lon),
+                      ...(bag.values.location.locationLabel.length > 0
+                        ? { address: bag.values.location.locationLabel }
+                        : {}),
+                    }}
+                    onChange={(next) => {
+                      // Numbers in, decimal strings out — the wire's spelling,
+                      // written at the seam so no other module has to know.
+                      bag.setLocation({
+                        ...bag.values.location,
+                        lat: next.lat === null ? null : String(next.lat),
+                        lon: next.lon === null ? null : String(next.lon),
+                        locationLabel: next.address ?? "",
+                      });
+                      bag.saveSoon();
+                    }}
+                  />
+                </div>
+              ) : undefined
+            }
+          />
 
-          <Typography.Title level={5}>
-            {t(LISTINGS_I18N_KEYS.composePhotos)}
-          </Typography.Title>
-          {props.gallerySlot}
-          {bag.fieldErrors[IMAGES_FIELD] ? (
-            <Typography.Text type="danger" data-testid="listings-composer-images-error">
-              {describe(bag.fieldErrors[IMAGES_FIELD]).message}
-            </Typography.Text>
+          {/* A heading is a promise that something follows it. With no gallery
+              and no named placeholder there is nothing to head. */}
+          {props.gallerySlot !== undefined || namedSlots ? (
+            <>
+              <Divider />
+              <Typography.Title level={5}>
+                {t(LISTINGS_I18N_KEYS.composePhotos)}
+              </Typography.Title>
+              {props.gallerySlot ?? (
+                <SlotPlaceholder name="gallerySlot" visibility="visible" />
+              )}
+              {bag.fieldErrors[IMAGES_FIELD] ? (
+                <Typography.Text type="danger" data-testid="listings-composer-images-error">
+                  {describe(bag.fieldErrors[IMAGES_FIELD]).message}
+                </Typography.Text>
+              ) : null}
+            </>
           ) : null}
 
           <Divider />
@@ -387,10 +604,8 @@ export function ListingComposerPage(
             {t(LISTINGS_I18N_KEYS.composeDetails)}
           </Typography.Title>
           {props.featuresError !== undefined ? (
-            <Alert
-              type="error"
-              showIcon
-              data-testid="listings-composer-features-failed"
+            <ErrorAlert
+              testId="listings-composer-features-failed"
               message={t(LISTINGS_I18N_KEYS.composeDetailsFailed)}
             />
           ) : props.featuresLoading === true ? (
@@ -453,10 +668,8 @@ export function ListingComposerPage(
         </Form>
 
         {bag.refusal?.kind === "invalid_draft" ? (
-          <Alert
-            type="error"
-            showIcon
-            data-testid="listings-composer-invalid"
+          <ErrorAlert
+            testId="listings-composer-invalid"
             message={t(LISTINGS_I18N_KEYS.composeInvalidSummary, {
               count: failedResults(bag.refusal.batch).length,
             })}
@@ -479,53 +692,56 @@ export function ListingComposerPage(
         {bag.saveError !== undefined && bag.saveError !== null ? (
           <ErrorAlert
             testId="listings-composer-save-error"
-            error={describe({
-              code: LISTINGS_I18N_KEYS.unknownError,
-              params: {},
-              status: 0,
-              message: undefined,
-              language: undefined,
-            })}
+            thrown={bag.saveError}
           />
         ) : null}
 
-        <Space>
-          <Button
-            disabled={!bag.saveGate.available}
-            loading={bag.saving}
-            data-testid="listings-composer-save"
-            data-analytics="none"
-            data-analytics-reason="business action — host app wraps with its own tracked()"
-            onClick={bag.save}
-          >
-            {t(bag.saving ? LISTINGS_I18N_KEYS.composeSaving : LISTINGS_I18N_KEYS.composeSave)}
-          </Button>
-
-          <Button
+        {/* One primary, and it LEADS. Two same-weight boxes side by side, the
+            filled one second, is a footer with no primary in it — which is
+            how it read on a phone, where the eye takes the first control as
+            the action. `Save draft` is the quiet way out, so it is quiet.
+            Each keeps its own reason directly under it, never a grey slab
+            under the pair. */}
+        {/* The footer is one SCOPE, so the reason both buttons are off is
+            written once and both point at it. "Choose a category" under
+            Publish and again under Save draft is one fact printed twice. */}
+        <PaneGate gate={actionAvailable()} testId="listings-composer-footer">
+        <Flex vertical gap={spacing[3]} align="flex-start">
+          <GatedButton
+            gate={bag.publishGate}
             type="primary"
-            disabled={!bag.publishGate.available}
+            size="large"
             loading={bag.publishing}
-            data-testid="listings-composer-publish"
+            testId="listings-composer-publish"
             data-analytics="none"
             data-analytics-reason="business action — host app wraps with its own tracked()"
             onClick={bag.publish}
           >
             {bag.publishing ? t(LISTINGS_I18N_KEYS.composePublishing) : publishLabel}
-          </Button>
+          </GatedButton>
 
-          {bag.saved ? (
-            <Typography.Text type="success" data-testid="listings-composer-saved">
-              {t(LISTINGS_I18N_KEYS.composeSaved)}
-            </Typography.Text>
-          ) : null}
-        </Space>
+          <Flex gap={spacing[3]} wrap align="flex-start">
+            <GatedButton
+              gate={bag.saveGate}
+              type="text"
+              loading={bag.saving}
+              testId="listings-composer-save"
+              data-analytics="none"
+              data-analytics-reason="business action — host app wraps with its own tracked()"
+              onClick={bag.save}
+            >
+              {t(bag.saving ? LISTINGS_I18N_KEYS.composeSaving : LISTINGS_I18N_KEYS.composeSave)}
+            </GatedButton>
 
-        {!bag.publishGate.available ? (
-          <Typography.Text type="secondary" data-testid="listings-composer-publish-blocked">
-            {t(bag.publishGate.block.code, bag.publishGate.block.params)}
-          </Typography.Text>
-        ) : null}
+            {bag.saved ? (
+              <Typography.Text type="success" data-testid="listings-composer-saved">
+                {t(LISTINGS_I18N_KEYS.composeSaved)}
+              </Typography.Text>
+            ) : null}
+          </Flex>
+        </Flex>
+        </PaneGate>
       </Flex>
-    </ListingsSkinTheme>
+    </SkinTheme>
   );
 }