@stapel/listings-react 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/listings-react",
-  "version": "0.2.0",
+  "version": "0.3.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": {
@@ -99,7 +99,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
     "@stapel/attributes-react": "^0.2.0",
-    "@stapel/core": "^0.15.0",
+    "@stapel/core": "^0.16.0",
     "@stapel/image": "^0.2.0",
     "@stapel/showcase": "^0.2.0",
     "@stapel/tokens": "^0.5.0",

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.2.0",
+  "version": "0.3.0",
   "defined": [],
   "flows": []
 }

package/src/default/FavoritesPane.tsx

@@ -10,17 +10,52 @@
 import type { ReactElement } from "react";
 import { Alert, Button, Empty, Flex, Space, Spin, Typography } from "antd";
 import { matchList, useDescribeFlowError, useT } from "@stapel/core";
+import type { LinkComponent } from "@stapel/core";
 import { useFavorites } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 import { ListingCard } from "./ListingCard.js";
+import type { ListingCardOpenProps } from "./ListingCard.js";
 import { ListingsSkinTheme } from "./theme.js";
 import type { ThemeModeProp } from "./types.js";
 
-export interface FavoritesPaneProps extends ThemeModeProp {
-  /** Where a card leads. The container owns routing. */
-  readonly hrefFor?: (id: number) => string;
-  readonly onOpen?: (id: number) => void;
+/** How a card in this grid opens — the same one-contract union `<ListingCard>`
+ * takes, one level up, so a pane cannot re-introduce the double navigation the
+ * card no longer allows. */
+export type FavoritesPaneOpenProps =
+  | {
+      /** Where a card leads. The container owns routing. */
+      readonly hrefFor: (id: number) => string;
+      /** The host's `<Link>`, so a click stays inside the SPA. */
+      readonly linkComponent?: LinkComponent;
+      readonly onOpen?: undefined;
+    }
+  | {
+      readonly onOpen: (id: number) => void;
+      readonly hrefFor?: undefined;
+      readonly linkComponent?: undefined;
+    }
+  | {
+      readonly hrefFor?: undefined;
+      readonly onOpen?: undefined;
+      readonly linkComponent?: undefined;
+    };
+
+export type FavoritesPaneProps = ThemeModeProp & FavoritesPaneOpenProps;
+
+/** The card's own open props for one row. One arm, never two. */
+function cardOpenProps(
+  props: FavoritesPaneOpenProps,
+  id: number
+): ListingCardOpenProps {
+  if (props.hrefFor !== undefined) {
+    const href = props.hrefFor(id);
+    return props.linkComponent !== undefined
+      ? { href, linkComponent: props.linkComponent }
+      : { href };
+  }
+  if (props.onOpen !== undefined) return { onOpen: props.onOpen };
+  return {};
 }
 
 export function FavoritesPane(props: FavoritesPaneProps): ReactElement {
@@ -82,13 +117,7 @@ export function FavoritesPane(props: FavoritesPaneProps): ReactElement {
             <Flex wrap gap={16} data-testid="listings-favorites-grid">
               {rows.map((row) => (
                 <div key={row.id} style={{ width: 240 }}>
-                  <ListingCard
-                    listing={row}
-                    {...(props.hrefFor !== undefined
-                      ? { href: props.hrefFor(row.id) }
-                      : {})}
-                    {...(props.onOpen !== undefined ? { onOpen: props.onOpen } : {})}
-                  />
+                  <ListingCard listing={row} {...cardOpenProps(props, row.id)} />
                 </div>
               ))}
             </Flex>

package/src/default/ListingCard.tsx

@@ -4,7 +4,15 @@
  * `@stapel/search-react` takes a `renderCard` slot and the container fills it
  * with this (spec §3.7 / §6.2 item 1). The two pairs never import each other;
  * the CONTAINER is the seam, which is why this component takes a plain card
- * row and a plain `href`/`onOpen` rather than reaching for a router.
+ * row and a plain `href` rather than reaching for a router.
+ *
+ * ── One click, one navigation ──────────────────────────────────────────────
+ *
+ * `href` and `onOpen` used to be two optional props, and a card given both
+ * navigated TWICE: the handler ran, and the browser then followed the anchor
+ * that was still on the button. They are now three arms of a union — link,
+ * button, or neither — and `linkComponent` rides on the link arm so a
+ * container can hand in its router's `<Link>` and keep the anchor.
  *
  * ── What it renders without asking the server anything else ────────────────
  *
@@ -16,13 +24,17 @@
  *
  * ── The heart is never hidden ──────────────────────────────────────────────
  *
- * A visitor sees it, blocked, with the reason and the sign-in CTA the
- * container attaches (`?next=`). Hiding it would teach nobody that
- * favourites exist (private-space canon §6.3, spec §6.2 item 6).
+ * A visitor sees it, blocked, with the reason IN WORDS beside it and the
+ * sign-in link the container supplies (`signIn`, typically `?next=<current>`).
+ * Hiding it would teach nobody that favourites exist (private-space canon
+ * §6.3, spec §6.2 item 6) — and until 0.3.0 the reason lived only in a tooltip
+ * on a disabled button, which receives no pointer events in any browser: a
+ * reason nobody could read, and no door to walk through.
  */
 import type { ReactElement, ReactNode } from "react";
 import { Button, Card, Flex, Tooltip, Typography } from "antd";
-import { useT } from "@stapel/core";
+import { useActionGate, useT } from "@stapel/core";
+import type { LinkComponent, SignInCtaProp } from "@stapel/core";
 import { FeatureBadges } from "@stapel/attributes-react/default";
 import type { ListingCard as ListingCardData } from "../api/types.js";
 import { asFeatureDaoList, featuresDtoFromDaoList, featuresFromDaoList } from "../model/features.js";
@@ -30,18 +42,53 @@ import { lifecycleCaption } from "../model/status.js";
 import { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { HeartIcon } from "./icons.js";
+import { SignInLink } from "./SignInLink.js";
 import { ListingPhoto } from "./ListingPhoto.js";
 import { ListingsSkinTheme } from "./theme.js";
 import type { ThemeModeProp } from "./types.js";
 
-export interface ListingCardProps extends ThemeModeProp {
+/**
+ * How the card opens — ONE of three, and the type says so.
+ *
+ * It used to be two optional props, and a caller that passed both got two
+ * navigations for one click: the handler ran and the browser then followed the
+ * anchor anyway. The storefront worked around it by passing `onOpen` only,
+ * which cost it a real anchor (no middle-click, no "open in new tab", nothing
+ * for a crawler to follow) on the most linkable element in the app.
+ *
+ * So the union has three arms and no fourth: a link, a button, or neither.
+ * `linkComponent` belongs to the link arm because it IS the link — handing a
+ * `<Link>` to a card that navigates by callback would be two answers to one
+ * question again.
+ */
+export type ListingCardOpenProps =
+  | {
+      /** Where the card leads. A plain path — the pair never calls
+       * `window.location` and never builds a router descriptor. */
+      readonly href: string;
+      /** The host's `<Link>`, so the click stays inside the SPA. Absent: an
+       * antd link-button carrying the `href`, which reloads the page in a
+       * router app — correct, just not fast. */
+      readonly linkComponent?: LinkComponent;
+      readonly onOpen?: undefined;
+    }
+  | {
+      /** The card opens by callback: rendered as a button, with no `href` for
+       * the browser to follow after the handler has already navigated. */
+      readonly onOpen: (id: number) => void;
+      readonly href?: undefined;
+      readonly linkComponent?: undefined;
+    }
+  | {
+      /** No open control at all — a card inside a screen that is already the
+       * listing. */
+      readonly href?: undefined;
+      readonly onOpen?: undefined;
+      readonly linkComponent?: undefined;
+    };
+
+export interface ListingCardBaseProps extends ThemeModeProp, SignInCtaProp {
   readonly listing: ListingCardData;
-  /** Where the card leads. The container owns routing, so this is a plain
-   * href a `<Link>` or an `<a>` can carry — the pair never calls
-   * `window.location`. */
-  readonly href?: string;
-  /** Called instead of following `href`, for a host with its own navigation. */
-  readonly onOpen?: (id: number) => void;
   /** Extra chrome the container adds (a `promoted` tag from search, say —
    * DSA Art. 26 marking belongs to the pair that receives it). */
   readonly badge?: ReactNode;
@@ -50,6 +97,73 @@ export interface ListingCardProps extends ThemeModeProp {
   readonly showFavorite?: boolean;
 }
 
+export type ListingCardProps = ListingCardBaseProps & ListingCardOpenProps;
+
+/**
+ * The one control that opens the card: an anchor, a button, or nothing.
+ *
+ * Exactly one of the three renders, so exactly one navigation happens per
+ * click. That is the whole fix — the branch below has no arm in which both a
+ * handler and an `href` reach the DOM.
+ */
+function OpenControl(
+  props: ListingCardOpenProps & { readonly listingId: number }
+): ReactElement | null {
+  const t = useT();
+  const label = t(LISTINGS_I18N_KEYS.cardOpen);
+
+  if (props.href !== undefined) {
+    const Link = props.linkComponent;
+    // The host's component is rendered as it comes: this pair has no CSS and
+    // no way to hand antd's button styling to a foreign element, and a wrapper
+    // element around a link is a click target that is not the link. A host
+    // that wants the antd look styles its own `<Link>` — it is one component,
+    // written once, and it is already the thing that knows the design system.
+    return Link !== undefined ? (
+      <Link
+        href={props.href}
+        aria-label={label}
+        data-testid="listings-card-open"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+      >
+        {label}
+      </Link>
+    ) : (
+      <Button
+        size="small"
+        type="link"
+        href={props.href}
+        data-testid="listings-card-open"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+      >
+        {label}
+      </Button>
+    );
+  }
+
+  if (props.onOpen !== undefined) {
+    const onOpen = props.onOpen;
+    return (
+      <Button
+        size="small"
+        type="link"
+        data-testid="listings-card-open"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+        onClick={() => {
+          onOpen(props.listingId);
+        }}
+      >
+        {label}
+      </Button>
+    );
+  }
+
+  return null;
+}
+
 export function ListingCard(props: ListingCardProps): ReactElement {
   const t = useT();
   const { listing } = props;
@@ -66,6 +180,8 @@ export function ListingCard(props: ListingCardProps): ReactElement {
       ? `${listing.price} ${listing.currency ?? ""}`.trim()
       : t(LISTINGS_I18N_KEYS.cardPriceAbsent);
 
+  const favoriteGate = useActionGate(favorite.gate);
+
   const favoriteLabel = t(
     favorite.favorited
       ? LISTINGS_I18N_KEYS.cardFavoriteRemove
@@ -127,21 +243,7 @@ export function ListingCard(props: ListingCardProps): ReactElement {
           ) : null}
 
           <Flex gap={8} align="center">
-            {props.href !== undefined || props.onOpen !== undefined ? (
-              <Button
-                size="small"
-                type="link"
-                {...(props.href !== undefined ? { href: props.href } : {})}
-                data-testid="listings-card-open"
-                data-analytics="none"
-                data-analytics-reason="business action — host app wraps with its own tracked()"
-                onClick={() => {
-                  props.onOpen?.(listing.id);
-                }}
-              >
-                {t(LISTINGS_I18N_KEYS.cardOpen)}
-              </Button>
-            ) : null}
+            <OpenControl {...props} listingId={listing.id} />
 
             {props.showFavorite === false ? null : (
               <Tooltip
@@ -171,6 +273,21 @@ export function ListingCard(props: ListingCardProps): ReactElement {
               </Tooltip>
             )}
           </Flex>
+
+          {/* The reason IN WORDS, plus the door. A tooltip on a disabled
+              button is a reason nobody can read (core's actionGate.ts says so
+              in as many words), and a reason with no next action leaves the
+              visitor hunting for the header — which is what the storefront
+              had to write a paragraph about instead of shipping the screen. */}
+          {props.showFavorite === false || favoriteGate.reason === undefined ? null : (
+            <Typography.Text
+              type="secondary"
+              data-testid="listings-card-favorite-blocked"
+            >
+              {favoriteGate.reason}
+              <SignInLink cta={props.signIn} testId="listings-card-sign-in" />
+            </Typography.Text>
+          )}
         </Flex>
       </Card>
     </ListingsSkinTheme>

package/src/default/ListingComposerPage.tsx

@@ -5,12 +5,29 @@
  * the component can be read top to bottom without knowing any of the other
  * pairs:
  *
- *   category   `categorySlot`  — the container's `<CategoryPickerField>`
+ *   category   `renderCategoryPicker` — the container's `<CategoryPickerField>`,
+ *                                given `setCategory` to call
  *   details    `features`      — the schema, drawn by `<FeatureFields>` (L0)
- *   photos     `gallerySlot`   — the container's `<MediaGalleryField>`, whose
- *                                bag is handed to the composer as `images`
+ *   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 ──────────────────
+ *
+ * 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).
+ *
+ * `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.
+ *
  * ── 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
@@ -55,6 +72,19 @@ import { ErrorAlert } from "./ErrorAlert.js";
 import { ListingsSkinTheme } from "./theme.js";
 import type { ThemeModeProp } from "./types.js";
 
+/**
+ * What `renderCategoryPicker` is handed: the current category and the ONLY
+ * function that changes it. Same shape as any other bag in this monorepo — the
+ * value plus the setter, never a setter alone.
+ */
+export interface ComposerCategorySlot {
+  /** The category the draft currently carries. Empty string: none chosen. */
+  readonly value: string;
+  /** Choose a category. Prunes the answers the new schema does not ask for
+   * (one render later, once `features` arrives) and reports upwards. */
+  readonly setCategory: (categoryId: string) => void;
+}
+
 export interface ListingComposerPageProps extends ThemeModeProp {
   /** Editing an existing listing; absent for a new one. */
   readonly listingId?: number;
@@ -63,7 +93,33 @@ export interface ListingComposerPageProps extends ThemeModeProp {
   readonly features: readonly FeatureDef[];
   readonly featuresLoading?: boolean;
   readonly featuresError?: unknown;
-  /** The category chooser. A slot for the same reason. */
+  /**
+   * The category chooser, handed the value and the setter. This is the slot a
+   * container fills with `@stapel/categories-react`'s `<CategoryPickerField>`:
+   *
+   * ```tsx
+   * renderCategoryPicker={({ value, setCategory }) => (
+   *   <CategoryPickerField
+   *     value={value === "" ? null : Number(value)}
+   *     onChange={(id) => setCategory(id === null ? "" : String(id))}
+   *   />
+   * )}
+   * ```
+   */
+  readonly renderCategoryPicker?: (slot: ComposerCategorySlot) => ReactNode;
+  /**
+   * The chosen category, when the container owns that state — the usual case,
+   * since the same id keys the `features` read.
+   */
+  readonly category?: string;
+  /** 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.
+   */
   readonly categorySlot?: ReactNode;
   /** The photo grid. Its bag is what `images` carries. */
   readonly gallerySlot?: ReactNode;
@@ -89,6 +145,10 @@ export function ListingComposerPage(
       : {}),
     editorTypes: BUILTIN_VALUE_EDITOR_TYPES,
     ...(props.images !== undefined ? { images: props.images } : {}),
+    ...(props.category !== undefined ? { category: props.category } : {}),
+    ...(props.onCategoryChange !== undefined
+      ? { onCategoryChange: props.onCategoryChange }
+      : {}),
     ...(props.onPublished !== undefined
       ? {
           // `listing_id` comes back in the response, so the callback never
@@ -160,16 +220,21 @@ export function ListingComposerPage(
             extra={t(LISTINGS_I18N_KEYS.composeCategoryHelp)}
             {...errorOf(CATEGORY_FIELD)}
           >
-            {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);
-                }}
-              />
-            )}
+            {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>
 
           {bag.droppedOnCategoryChange.length > 0 ? (

package/src/default/SignInLink.tsx

@@ -0,0 +1,54 @@
+/**
+ * The door beside a blocked control.
+ *
+ * `actionBlocked` ended the grey-rectangle incident by making every
+ * switched-off control state its reason. It did not end the next problem:
+ * "sign in to add this to favourites" is a reason whose next action is a LINK,
+ * and this pair rendered the sentence and stopped there — leaving the visitor
+ * to find the header themselves (storefront Wave D, G-3).
+ *
+ * WHERE that link goes is the container's business, never the pair's: the
+ * storefront's is `/login?next=<current>`, a tenant app's may be a modal. So
+ * the shape is core's `SignInCta` — `{href}` or `{onSignIn}`, never both — and
+ * the copy is this pair's, because core floors `en` and `ru` while this pair
+ * also ships `es`.
+ *
+ * A host that routes internally passes `onSignIn`; the `href` arm renders a
+ * plain anchor on purpose, because arriving at a sign-in page is one of the
+ * few navigations a full load costs nothing.
+ */
+import type { ReactElement } from "react";
+import { Typography } from "antd";
+import { useT } from "@stapel/core";
+import type { SignInCta } from "@stapel/core";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+
+export interface SignInLinkProps {
+  /** Absent: no link — a host with no sign-in route shows the reason alone. */
+  readonly cta: SignInCta | undefined;
+  readonly testId: string;
+}
+
+export function SignInLink(props: SignInLinkProps): ReactElement | null {
+  const t = useT();
+  const { cta } = props;
+  if (cta === undefined) return null;
+  // The separating space belongs HERE, not at the call site: a reason with no
+  // door must render as exactly its own sentence, and a `{" "}` left behind by
+  // an absent link is a trailing space in every caller's assertion.
+  return (
+    <>
+      {" "}
+      <Typography.Link
+        data-testid={props.testId}
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+        {...(cta.href !== undefined
+          ? { href: cta.href }
+          : { onClick: cta.onSignIn })}
+      >
+        {t(LISTINGS_I18N_KEYS.cardSignIn)}
+      </Typography.Link>
+    </>
+  );
+}

package/src/default/index.ts

@@ -15,21 +15,33 @@
  * ```
  */
 export { ListingCard } from "./ListingCard.js";
-export type { ListingCardProps } from "./ListingCard.js";
+export type {
+  ListingCardProps,
+  ListingCardBaseProps,
+  ListingCardOpenProps,
+} from "./ListingCard.js";
 export { ListingDetailPane } from "./ListingDetailPane.js";
 export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
 export { ListingComposerPage } from "./ListingComposerPage.js";
-export type { ListingComposerPageProps } from "./ListingComposerPage.js";
+export type {
+  ListingComposerPageProps,
+  ComposerCategorySlot,
+} from "./ListingComposerPage.js";
 export { MyListingsPane } from "./MyListingsPane.js";
 export type { MyListingsPaneProps } from "./MyListingsPane.js";
 export { FavoritesPane } from "./FavoritesPane.js";
-export type { FavoritesPaneProps } from "./FavoritesPane.js";
+export type {
+  FavoritesPaneProps,
+  FavoritesPaneOpenProps,
+} from "./FavoritesPane.js";
 
 export { LifecycleTag, ListingStatusBlock, ModerationNote } from "./StatusTags.js";
 export type { ListingStatusProps } from "./StatusTags.js";
 export { ListingPhoto } from "./ListingPhoto.js";
 export type { ListingPhotoProps } from "./ListingPhoto.js";
 export { ErrorAlert } from "./ErrorAlert.js";
+export { SignInLink } from "./SignInLink.js";
+export type { SignInLinkProps } from "./SignInLink.js";
 export { ListingsSkinTheme } from "./theme.js";
 export type { ListingsSkinThemeProps } from "./theme.js";
 export type { ThemeModeProp } from "./types.js";

package/src/headless/ListingComposer.tsx

@@ -125,6 +125,23 @@ export interface UseListingComposerOptions {
   /** The upload queue. Absent: no gallery, and `images` is set through
    * `setValue` by whatever the host uses instead. */
   readonly images?: ListingImagesBag;
+  /**
+   * The chosen category, when the CONTAINER owns that state.
+   *
+   * The category is the one value the composer cannot own alone: the picker
+   * lives in `@stapel/categories-react` and the schema read
+   * (`useCategoryFeatures(id)`) that fills `features` is keyed by it, so the
+   * container holds it either way. Passing it here makes this hook controlled
+   * on that field — `values.categoryId` mirrors it, and `setCategory` reports
+   * upwards instead of writing local state that would then disagree with the
+   * schema on screen.
+   *
+   * Absent: uncontrolled, exactly as before.
+   */
+  readonly category?: string;
+  /** Called by `setCategory`, whether or not `category` is controlled. This is
+   * how a container learns which category to read the schema for. */
+  readonly onCategoryChange?: (categoryId: string) => void;
   /** Seed for a brand-new draft (a category preselected from the URL, say). */
   readonly initialValues?: Partial<ListingDraftValues>;
   onDraftCreated?: (draft: ListingDraft) => void;
@@ -245,9 +262,19 @@ export function useListingComposer(
   // The gallery is the upload bag's, whenever there is one: two sources of
   // truth for the same list is how a publish sends photos the person removed.
   const images = options.images?.refs ?? values.images;
+  // Same rule for the category when the container holds it: the schema on
+  // screen is read for the container's id, so a local copy that drifted from
+  // it would ask one category's questions and file the listing under another.
+  const controlledCategory = options.category;
   const effectiveValues: ListingDraftValues = useMemo(
-    () => ({ ...values, images }),
-    [values, images]
+    () => ({
+      ...values,
+      images,
+      ...(controlledCategory !== undefined
+        ? { categoryId: controlledCategory }
+        : {}),
+    }),
+    [values, images, controlledCategory]
   );
 
   const featuresDto = useMemo(
@@ -435,14 +462,20 @@ export function useListingComposer(
     },
     setCategory: (categoryId) => {
       setSaved(false);
-      setValues((current) => {
-        if (current.categoryId === categoryId) return current;
-        // The features of the NEW category are not known yet (the container's
-        // schema read has not run), so nothing is pruned here — pruning
-        // happens in the effect below, once they arrive. Recording the
-        // intent, not guessing the outcome.
-        return { ...current, categoryId };
-      });
+      // Told upwards FIRST and unconditionally: the container's schema read is
+      // keyed by this id, and it must be asked for even when the composer is
+      // uncontrolled — that is the wire `features` arrives on.
+      options.onCategoryChange?.(categoryId);
+      if (controlledCategory === undefined) {
+        setValues((current) => {
+          if (current.categoryId === categoryId) return current;
+          // The features of the NEW category are not known yet (the
+          // container's schema read has not run), so nothing is pruned here —
+          // pruning happens in the effect below, once they arrive. Recording
+          // the intent, not guessing the outcome.
+          return { ...current, categoryId };
+        });
+      }
       setDropped([]);
       setRefusal(undefined);
     },

package/src/i18n/es.ts

@@ -70,6 +70,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.card.favorite_add": "Guardar en favoritos",
   "listings.card.favorite_remove": "Quitar de favoritos",
   "listings.card.open": "Abrir",
+  "listings.card.sign_in": "Iniciar sesión",
 
   "listings.detail.loading": "Cargando el anuncio…",
   "listings.detail.load_failed": "No pudimos cargar este anuncio",

package/src/i18n/keys.ts

@@ -63,6 +63,8 @@ export const LISTINGS_I18N_KEYS = {
   cardFavoriteAdd: "listings.card.favorite_add",
   cardFavoriteRemove: "listings.card.favorite_remove",
   cardOpen: "listings.card.open",
+  /** The door beside a blocked favourite: the container supplies WHERE. */
+  cardSignIn: "listings.card.sign_in",
 
   // ── detail ───────────────────────────────────────────────────────────────
   detailLoading: "listings.detail.loading",
@@ -218,6 +220,7 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.card.favorite_add": "Save to favourites",
   "listings.card.favorite_remove": "Remove from favourites",
   "listings.card.open": "Open",
+  "listings.card.sign_in": "Sign in",
 
   "listings.detail.loading": "Loading the listing…",
   "listings.detail.load_failed": "We could not load this listing",

package/src/i18n/ru.ts

@@ -86,6 +86,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.card.favorite_add": "В избранное",
   "listings.card.favorite_remove": "Убрать из избранного",
   "listings.card.open": "Открыть",
+  "listings.card.sign_in": "Войти",
 
   "listings.detail.loading": "Загружаем объявление…",
   "listings.detail.load_failed": "Не удалось загрузить объявление",