@stapel/listings-react 0.10.0 → 0.12.0

package/src/default/ListingDetailPane.tsx

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

package/src/default/ListingSerpCard.tsx

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

package/src/default/index.ts

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

package/src/default/types.ts

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

package/src/headless/ListingComposer.tsx

@@ -39,7 +39,12 @@ import {
 import type { ListingDraftValues, ListingLocation } from "../model/draft.js";
 import { asFeatureDaoList } from "../model/features.js";
 import { featuresDtoFromDaoList } from "../model/features.js";
-import { mirrorDraft, publishRefusal } from "../model/validation.js";
+import {
+  LISTING_FIELD_ORDER,
+  envelopeFieldErrors,
+  mirrorDraft,
+  publishRefusal,
+} from "../model/validation.js";
 import type { PublishRefusal } from "../model/validation.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { useMandateGate } from "./useMandateGate.js";
@@ -197,6 +202,17 @@ export interface ListingComposerBag {
   readonly fieldErrors: Readonly<Record<string, FlowError>>;
   /** The server's last publish refusal, unrouted, for a summary line. */
   readonly refusal: PublishRefusal | undefined;
+  /**
+   * The first field the mirror is refusing, in the order the form asks for it
+   * (`LISTING_FIELD_ORDER`, then the category's features in schema order), or
+   * `undefined` when nothing is refused.
+   *
+   * The publish gate can say "10 required details are still empty" while not
+   * one of them is on screen — on a phone the attribute region starts nearly
+   * two viewports below the fold — and a count with nowhere to go is a dead
+   * end. This is what a skin's "take me there" control aims at.
+   */
+  readonly firstUnsatisfied: string | undefined;
   /** Value types this build cannot draw — the fact, from attributes-react. */
   readonly unsupported: readonly string[];
 
@@ -358,12 +374,36 @@ export function useListingComposer(
     (existing.data.title ?? "").length === 0 &&
     (existing.data.description ?? "").length === 0;
 
+  // A save-draft/create 400 names its field in the envelope rather than in a
+  // batch, so it takes the other door onto the same routing table. Without it
+  // the composer painted a banner and left every control clean — the person
+  // was told something was wrong and not what (blocker C2).
+  const saveThrown: unknown = saveDraft.error ?? createDraft.error;
   const fieldErrors: Readonly<Record<string, FlowError>> = useMemo(() => {
     const shown = showErrors ? mirror : {};
-    return refusal?.kind === "invalid_draft"
-      ? { ...shown, ...refusal.fieldErrors }
-      : shown;
-  }, [showErrors, mirror, refusal]);
+    const routed =
+      refusal?.kind === "invalid_draft"
+        ? refusal.fieldErrors
+        : refusal?.kind === "error"
+          ? envelopeFieldErrors(refusal.error)
+          : {};
+    return { ...shown, ...envelopeFieldErrors(saveThrown), ...routed };
+  }, [showErrors, mirror, refusal, saveThrown]);
+
+  // The order is the FORM's, not the record's — see `LISTING_FIELD_ORDER`.
+  // A key in neither list (a server field with no control of its own) is still
+  // named rather than dropped: something is refusing, and saying which is
+  // better than saying nothing.
+  const firstUnsatisfied: string | undefined = useMemo(() => {
+    const refused = mirror;
+    for (const field of LISTING_FIELD_ORDER) {
+      if (refused[field] !== undefined) return field;
+    }
+    for (const feature of options.features) {
+      if (refused[feature.slug] !== undefined) return feature.slug;
+    }
+    return Object.keys(refused)[0];
+  }, [mirror, options.features]);
 
   const listingState: LoadState<ListingDetailData> | undefined =
     options.listingId === undefined
@@ -558,6 +598,7 @@ export function useListingComposer(
     mirror,
     fieldErrors,
     refusal,
+    firstUnsatisfied,
     unsupported,
 
     saveGate,
@@ -568,7 +609,7 @@ export function useListingComposer(
     saving: busy,
     publishing: publishListing.isPending,
     saved,
-    saveError: saveDraft.error ?? createDraft.error,
+    saveError: saveThrown,
     outcome,
   };
 }

package/src/headless/ListingDetail.tsx

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

package/src/i18n/es.ts

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

package/src/i18n/keys.ts

@@ -133,6 +133,10 @@ export const LISTINGS_I18N_KEYS = {
   composeTooManyImages: "listings.compose.too_many_images",
   composeDetails: "listings.compose.details",
   composeDetailsLoading: "listings.compose.details_loading",
+  /** No category has been chosen yet, so nothing is in flight and nothing will
+   * be until one is. The section used to print the LOADING sentence in this
+   * state — a spinner-shaped claim about a request that was never made. */
+  composeDetailsNoCategory: "listings.compose.details_no_category",
   composeDetailsFailed: "listings.compose.details_failed",
   composeDetailsEmpty: "listings.compose.details_empty",
   composeCountable: "listings.compose.countable",
@@ -159,6 +163,10 @@ export const LISTINGS_I18N_KEYS = {
    * pointed at nothing highlighted, because the mirror only becomes visible
    * once the person has tried to publish. */
   composeBlockedIncomplete: "listings.compose.blocked.incomplete",
+  /** The way from the blocked-submit COUNT to the first field it is counting.
+   * The count is printed at the foot of a 7000px form whose required fields
+   * are two viewports up; a number nobody can act on is not help. */
+  composeShowFirstMissing: "listings.compose.show_first_missing",
   composeBlockedDetailsUnavailable: "listings.compose.blocked.details_unavailable",
 
   // ── the owner's dashboard ────────────────────────────────────────────────
@@ -220,7 +228,11 @@ export const LISTINGS_I18N_KEYS = {
   // ── nav labels ───────────────────────────────────────────────────────────
   navDetail: "listings.nav.detail",
   navCompose: "listings.nav.compose",
+  // The compact wording a phone dock uses — `NavEntry.shortLabelKey`. The
+  // verb, not the sentence: a dock cell is ten characters wide.
+  navComposeShort: "listings.nav.compose.short",
   navMine: "listings.nav.mine",
+  navMineShort: "listings.nav.mine.short",
   navFavorites: "listings.nav.favorites",
 } as const;
 
@@ -323,6 +335,8 @@ export const listingsI18nBundleEn: Record<string, string> = {
     "A listing can carry at most {max} photos",
   "listings.compose.details": "Details",
   "listings.compose.details_loading": "Loading what this category asks for…",
+  "listings.compose.details_no_category":
+    "Choose a category first — what it asks for appears here.",
   "listings.compose.details_failed":
     "We could not load what this category asks for",
   "listings.compose.details_empty": "This category asks for no extra details",
@@ -356,6 +370,7 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.compose.blocked.mirror":
     "Fix the highlighted fields first",
   "listings.compose.blocked.incomplete": "{count} required details are still empty",
+  "listings.compose.show_first_missing": "Take me to the first empty field",
   "listings.compose.blocked.details_unavailable":
     "We could not load what this category asks for, so we cannot check the form",
 
@@ -417,7 +432,9 @@ export const listingsI18nBundleEn: Record<string, string> = {
 
   "listings.nav.detail": "Listing",
   "listings.nav.compose": "Post a listing",
+  "listings.nav.compose.short": "Post",
   "listings.nav.mine": "My listings",
+  "listings.nav.mine.short": "Listings",
   "listings.nav.favorites": "Favourites",
 };
 

package/src/i18n/ru.ts

@@ -146,6 +146,8 @@ export const listingsI18nBundleRu: I18nDictionary = {
     "К объявлению можно приложить не больше {max} фото",
   "listings.compose.details": "Характеристики",
   "listings.compose.details_loading": "Загружаем характеристики категории…",
+  "listings.compose.details_no_category":
+    "Сначала выберите категорию — здесь появится то, что она спрашивает.",
   "listings.compose.details_failed":
     "Не удалось загрузить характеристики категории",
   "listings.compose.details_empty":
@@ -176,6 +178,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.compose.blocked.busy":
     "Секунду — предыдущее изменение ещё сохраняется",
   "listings.compose.blocked.incomplete": "Не заполнено обязательных деталей: {count}",
+  "listings.compose.show_first_missing": "Перейти к первому незаполненному полю",
   "listings.compose.blocked.mirror": "Сначала поправьте отмеченные поля",
   "listings.compose.blocked.details_unavailable":
     "Не удалось загрузить характеристики категории, поэтому проверить форму нельзя",
@@ -237,7 +240,9 @@ export const listingsI18nBundleRu: I18nDictionary = {
 
   "listings.nav.detail": "Объявление",
   "listings.nav.compose": "Подать объявление",
+  "listings.nav.compose.short": "Подать",
   "listings.nav.mine": "Мои объявления",
+  "listings.nav.mine.short": "Мои",
   "listings.nav.favorites": "Избранное",
 };
 

package/src/index.ts

@@ -152,6 +152,7 @@ export {
   featuresFromDaoList,
   unreadableFeatureCount,
 } from "./model/features.js";
+export type { FeatureCopySource } from "./model/features.js";
 
 // ── model: validation, the mirror and the publish-400 split ──────────────────
 export {
@@ -159,8 +160,10 @@ export {
   DEFAULT_DRAFT_LIMITS,
   DESCRIPTION_FIELD,
   IMAGES_FIELD,
+  LOCATION_FIELD,
   PRICE_FIELD,
   TITLE_FIELD,
+  envelopeFieldErrors,
   failedResults,
   isBatchValid,
   listingFieldErrors,