@stapel/listings-react 0.7.0 → 0.8.0

package/src/headless/Favorites.tsx

@@ -13,7 +13,10 @@ import type { ListingCard, ListingPageParams } from "../api/types.js";
 import { useMyFavorites } from "../model/queries.js";
 import { useFavoriteListing } from "../model/mutations.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import { useMandateGate } from "./useMandateGate.js";
+import {
+  LISTINGS_ELEVATION_ACTIONS,
+  useElevatableMandateGate,
+} from "./useMandateGate.js";
 
 /**
  * Saving something for later — first-class in stapel-listings (a `Favorite`
@@ -48,23 +51,28 @@ export function useFavoriteToggle(
   id: number,
   favorited: boolean | null | undefined
 ): FavoriteToggleBag {
-  const mandate = useMandateGate();
+  const { gate: mandate, elevation } = useElevatableMandateGate(
+    LISTINGS_ELEVATION_ACTIONS.favorite
+  );
   const mutation = useFavoriteListing();
   const gate = firstBlock(
     mandate,
-    mutation.isPending
+    mutation.isPending || elevation.pending
       ? actionBlocked(LISTINGS_I18N_KEYS.blockedInFlight)
       : actionAvailable()
   );
   return {
     favorited: favorited === true,
     gate,
+    // On a host with auto-anonymous wired, the first heart an anonymous
+    // visitor presses mints their account and then saves — one press, no
+    // form, nothing said about it. Everywhere else `run` performs directly.
     toggle: () => {
       if (!gate.available) return;
-      mutation.mutate({ id, favorited: favorited !== true });
+      elevation.run(() => mutation.mutate({ id, favorited: favorited !== true }));
     },
-    inFlight: mutation.isPending,
-    error: mutation.error,
+    inFlight: mutation.isPending || elevation.pending,
+    error: mutation.error ?? elevation.error,
   };
 }
 
@@ -92,7 +100,18 @@ export interface UseFavoritesOptions {
 /** The favourites page: a real keyset list, unlike the owner's own listings
  * (see `MyListings.tsx` for why those are different). */
 export function useFavorites(options: UseFavoritesOptions = {}): FavoritesBag {
-  const gate = useMandateGate();
+  // The READ side of elevation, and the one place `identified` is the right
+  // question. A guest who saved listings must be able to come back and see
+  // them — an account that can save and cannot re-read is worse than the
+  // refusal it replaced — but a visitor who has never elevated has nothing
+  // here, so this page must not mint just to render. `covers` alone would
+  // open it for them and buy a 401.
+  const { gate: mandateGate, elevation } = useElevatableMandateGate(
+    LISTINGS_ELEVATION_ACTIONS.favorite
+  );
+  const gate = elevation.covers && !elevation.identified
+    ? actionBlocked(LISTINGS_I18N_KEYS.blockedSignIn)
+    : mandateGate;
   const [page, setPage] = useState<ListingPageParams>(
     options.limit !== undefined ? { limit: options.limit } : {}
   );

package/src/headless/ListingDetail.tsx

@@ -21,7 +21,10 @@ import { asFeatureDaoList, featuresFromDaoList, unreadableFeatureCount } from ".
 import { listingStatusView } from "../model/status.js";
 import type { ListingStatusView } from "../model/status.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import { useMandateGate } from "./useMandateGate.js";
+import {
+  LISTINGS_ELEVATION_ACTIONS,
+  useElevatableMandateGate,
+} from "./useMandateGate.js";
 
 /**
  * `images` is `string[] | NULL` on the wire, and the null is the SERVER
@@ -110,7 +113,9 @@ export function useListingDetail(
   const detail = useListing(id);
   const probe = useListingStatus(id);
   const favorite = useFavoriteListing();
-  const mandate = useMandateGate();
+  const { gate: mandate, elevation } = useElevatableMandateGate(
+    LISTINGS_ELEVATION_ACTIONS.favorite
+  );
 
   const state: LoadState<ListingDetailData> =
     detail.status === "error"
@@ -178,7 +183,7 @@ export function useListingDetail(
 
   const favoriteGate = firstBlock(
     mandate,
-    favorite.isPending
+    favorite.isPending || elevation.pending
       ? actionBlocked(LISTINGS_I18N_KEYS.blockedInFlight)
       : actionAvailable(),
     detail.data === undefined
@@ -206,9 +211,11 @@ export function useListingDetail(
     favoriteGate,
     toggleFavorite: () => {
       if (!favoriteGate.available) return;
-      favorite.mutate({ id, favorited: isFavorited !== true });
+      // Mints the anonymous account first where the host permits it for this
+      // action; a direct call everywhere else.
+      elevation.run(() => favorite.mutate({ id, favorited: isFavorited !== true }));
     },
-    favoriteInFlight: favorite.isPending,
+    favoriteInFlight: favorite.isPending || elevation.pending,
     refetch: () => {
       void detail.refetch();
       void probe.refetch();

package/src/headless/useMandateGate.ts

@@ -1,8 +1,24 @@
-import { matchMandate, useMandate } from "@stapel/core";
-import type { ActionAvailability } from "@stapel/core";
+import { matchMandate, useElevation, useMandate } from "@stapel/core";
+import type { ActionAvailability, Elevation } from "@stapel/core";
 import { actionAvailable, actionBlocked } from "@stapel/core";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 
+/**
+ * The names this pair's gated writes use when asking core's elevation seam
+ * whether an anonymous visitor may be given an identity instead of a
+ * refusal. A host lists the ones it permits (see `ElevationSource.actions`);
+ * anything it leaves out keeps its wall.
+ *
+ * Only `favorite` is named. Publishing a listing is deliberately absent and
+ * stays absent: a seller who cannot be reached again is not a seller, and an
+ * automatically-minted account is exactly that. Saving something for later
+ * is the opposite case — losing a shortlist because a stranger had not
+ * registered is friction with nothing behind it.
+ */
+export const LISTINGS_ELEVATION_ACTIONS = {
+  favorite: "listings.favorite",
+} as const;
+
 /**
  * "May this person act at all?" — the first gate on every write in the pair.
  *
@@ -28,13 +44,41 @@ import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
  * than throwing, so a pair rendered in a host that never wired the axis
  * degrades to "we could not check" — visible, fixable, and not a blank page.
  */
-export function useMandateGate(): ActionAvailability {
+export function useMandateGate(action?: string): ActionAvailability {
+  return useElevatableMandateGate(action).gate;
+}
+
+/**
+ * The same gate, with the elevation handle the caller needs to ACT on it.
+ *
+ * A control that passes an `action` is saying "for this one act, an
+ * anonymous visitor may be given an identity rather than a refusal" — and
+ * then it must run its write through `elevation.run`, or the write goes out
+ * before the account exists and buys a 401. The two halves are returned
+ * together so a caller cannot take the unblocked gate and forget the mint.
+ *
+ * Passing no `action` is the default and the majority: publishing, saving a
+ * draft, marking something sold. Those keep the wall.
+ */
+export function useElevatableMandateGate(action?: string): {
+  readonly gate: ActionAvailability;
+  readonly elevation: Elevation;
+} {
   const mandate = useMandate();
-  return matchMandate<ActionAvailability>(mandate, {
+  const elevation = useElevation(action);
+  const gate = matchMandate<ActionAvailability>(mandate, {
     member: () => actionAvailable(),
     guest: () => actionBlocked(LISTINGS_I18N_KEYS.blockedGuest),
-    anonymous: () => actionBlocked(LISTINGS_I18N_KEYS.blockedSignIn),
+    // The one arm elevation changes. An identity can be minted at the moment
+    // of the act for the actions the host listed, so the control is offered
+    // rather than refused — and the mandate axis itself is untouched, which
+    // is what keeps the composer's wall standing for the same visitor.
+    anonymous: () =>
+      elevation.covers
+        ? actionAvailable()
+        : actionBlocked(LISTINGS_I18N_KEYS.blockedSignIn),
     asking: () => actionBlocked(LISTINGS_I18N_KEYS.blockedMandateUnknown),
     unavailable: () => actionBlocked(LISTINGS_I18N_KEYS.blockedMandateUnknown),
   });
+  return { gate, elevation };
 }

package/src/i18n/es.ts

@@ -32,6 +32,8 @@ export const listingsI18nBundleEs: I18nDictionary = {
     "Estado de anuncio desconocido: «{status}»",
   "error.400.publish_validation_failed":
     "El anuncio no pasó la revisión y no se publicó",
+  "error.403.listing_anonymous_not_allowed":
+    "Para publicar un anuncio, inicia sesión o crea una cuenta",
   "error.403.listing_not_owner": "Este anuncio no es tuyo",
   "error.404.listing_not_found": "No se encontró el anuncio",
   "error.409.already_favorited": "El anuncio ya está en favoritos",
@@ -72,7 +74,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.card.price_absent": "Precio a consultar",
   "listings.card.favorite_add": "Guardar en favoritos",
   "listings.card.favorite_remove": "Quitar de favoritos",
-  "listings.card.open": "Abrir",
+  "listings.card.untitled": "Anuncio sin título",
   "listings.card.sign_in": "Iniciar sesión",
 
   "listings.detail.loading": "Cargando el anuncio…",

package/src/i18n/generated/errors.es.gen.ts

@@ -8,7 +8,7 @@ import type { ListingsErrorCode } from "./errors.gen.js";
 /**
  * `es` texts for the backend error codes this catalog carries.
  *
- * PARTIAL, and deliberately typed to say so: 22 key(s) owned by
+ * PARTIAL, and deliberately typed to say so: 23 key(s) owned by
  * stapel_attributes, stapel_listings are absent, because that owner ships no locale catalog
  * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
  * artifact via the en bundle; the pair layers its own authored `es`

package/src/i18n/generated/errors.gen.ts

@@ -74,6 +74,7 @@ export const LISTINGS_ERRORS = {
   "error.401.unauthorized": { status: 401, params: [], remediation: "reauthenticate", en: "Authentication required" },
   "error.402.payment_required": { status: 402, params: [], remediation: "retry", en: "Payment required" },
   "error.403.forbidden": { status: 403, params: [], remediation: "retry", en: "You do not have permission to perform this action" },
+  "error.403.listing_anonymous_not_allowed": { status: 403, params: [], remediation: "retry", en: "A guest account may not publish a listing" },
   "error.403.listing_not_owner": { status: 403, params: [], remediation: "retry", en: "Not your listing" },
   "error.403.network_blocked": { status: 403, params: [], remediation: "contact_support", en: "Requests from this network are not allowed" },
   "error.403.verification_enrollment_required": { status: 403, params: [], remediation: "verify", en: "Verification factor enrollment required" },
@@ -144,6 +145,7 @@ export const LISTINGS_ERROR_CODES: readonly ListingsErrorCode[] = [
   "error.401.unauthorized",
   "error.402.payment_required",
   "error.403.forbidden",
+  "error.403.listing_anonymous_not_allowed",
   "error.403.listing_not_owner",
   "error.403.network_blocked",
   "error.403.verification_enrollment_required",
@@ -216,6 +218,7 @@ export const listingsErrorBundleEn: Record<ListingsErrorCode, string> = {
   "error.401.unauthorized": "Authentication required",
   "error.402.payment_required": "Payment required",
   "error.403.forbidden": "You do not have permission to perform this action",
+  "error.403.listing_anonymous_not_allowed": "A guest account may not publish a listing",
   "error.403.listing_not_owner": "Not your listing",
   "error.403.network_blocked": "Requests from this network are not allowed",
   "error.403.verification_enrollment_required": "Verification factor enrollment required",

package/src/i18n/generated/errors.json

@@ -326,6 +326,13 @@
     "remediation": "retry",
     "en": "You do not have permission to perform this action"
   },
+  {
+    "code": "error.403.listing_anonymous_not_allowed",
+    "status": 403,
+    "params": [],
+    "remediation": "retry",
+    "en": "A guest account may not publish a listing"
+  },
   {
     "code": "error.403.listing_not_owner",
     "status": 403,

package/src/i18n/generated/errors.ru.gen.ts

@@ -8,7 +8,7 @@ import type { ListingsErrorCode } from "./errors.gen.js";
 /**
  * `ru` texts for the backend error codes this catalog carries.
  *
- * PARTIAL, and deliberately typed to say so: 22 key(s) owned by
+ * PARTIAL, and deliberately typed to say so: 23 key(s) owned by
  * stapel_attributes, stapel_listings are absent, because that owner ships no locale catalog
  * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
  * artifact via the en bundle; the pair layers its own authored `ru`

package/src/i18n/keys.ts

@@ -62,7 +62,17 @@ export const LISTINGS_I18N_KEYS = {
   cardPriceAbsent: "listings.card.price_absent",
   cardFavoriteAdd: "listings.card.favorite_add",
   cardFavoriteRemove: "listings.card.favorite_remove",
-  cardOpen: "listings.card.open",
+  /**
+   * The accessible name of a card whose listing has no title.
+   *
+   * The whole card is ONE anchor now, and an anchor's name is its `aria-label`
+   * — so a titleless listing would otherwise be a link announced as nothing at
+   * all, in a list of forty.
+   *
+   * This replaces `listings.card.open` (retired), which named a separate
+   * "Open" control that no longer exists: the card itself is the control.
+   */
+  cardUntitled: "listings.card.untitled",
   /** The door beside a blocked favourite: the container supplies WHERE. */
   cardSignIn: "listings.card.sign_in",
 
@@ -246,7 +256,7 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.card.price_absent": "Price on request",
   "listings.card.favorite_add": "Save to favourites",
   "listings.card.favorite_remove": "Remove from favourites",
-  "listings.card.open": "Open",
+  "listings.card.untitled": "Untitled listing",
   "listings.card.sign_in": "Sign in",
 
   "listings.detail.loading": "Loading the listing…",

package/src/i18n/ru.ts

@@ -48,6 +48,8 @@ export const listingsI18nBundleRu: I18nDictionary = {
     "Неизвестный статус объявления: «{status}»",
   "error.400.publish_validation_failed":
     "Объявление не прошло проверку и не опубликовано",
+  "error.403.listing_anonymous_not_allowed":
+    "Чтобы подать объявление, войдите или зарегистрируйтесь",
   "error.403.listing_not_owner": "Это не ваше объявление",
   "error.404.listing_not_found": "Объявление не найдено",
   "error.409.already_favorited": "Объявление уже в избранном",
@@ -88,7 +90,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.card.price_absent": "Цена по запросу",
   "listings.card.favorite_add": "В избранное",
   "listings.card.favorite_remove": "Убрать из избранного",
-  "listings.card.open": "Открыть",
+  "listings.card.untitled": "Объявление без названия",
   "listings.card.sign_in": "Войти",
 
   "listings.detail.loading": "Загружаем объявление…",

package/src/index.ts

@@ -214,7 +214,11 @@ export type {
 
 // ── headless (renderless components + their bags) ────────────────────────────
 export { ListingsProvider } from "./headless/ListingsProvider.js";
-export { useMandateGate } from "./headless/useMandateGate.js";
+export {
+  useMandateGate,
+  useElevatableMandateGate,
+  LISTINGS_ELEVATION_ACTIONS,
+} from "./headless/useMandateGate.js";
 export { ListingDetail, useListingDetail } from "./headless/ListingDetail.js";
 export type {
   ListingDetailBag,