@stapel/listings-react 0.1.0

package/src/default/ListingCard.tsx

@@ -0,0 +1,178 @@
+/**
+ * `<ListingCard>` — the one component of this pair that another pair renders.
+ *
+ * `@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.
+ *
+ * ── What it renders without asking the server anything else ────────────────
+ *
+ * Badges. `features_badges` is a stored DAO projection, and a DAO carries the
+ * display config beside the value, so `formatFeatureValue` can render
+ * "1200 W" from the row alone — no category fetch, no second request per
+ * card. That property is the whole reason the projection exists, and it is
+ * what makes a grid of forty cards cost one query.
+ *
+ * ── 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).
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Button, Card, Flex, Tooltip, Typography } from "antd";
+import { useT } 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";
+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 { ListingPhoto } from "./ListingPhoto.js";
+import { ListingsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface ListingCardProps extends ThemeModeProp {
+  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;
+  /** Hide the favourite control entirely — for a context where it makes no
+   * sense (the owner's own dashboard). NOT a way to hide it from visitors. */
+  readonly showFavorite?: boolean;
+}
+
+export function ListingCard(props: ListingCardProps): ReactElement {
+  const t = useT();
+  const { listing } = props;
+  const favorite = useFavoriteToggle(listing.id, listing.is_favorited);
+
+  const badgeDaos = asFeatureDaoList(listing.features_badges);
+  const badgeFeatures = featuresFromDaoList(badgeDaos);
+  const badgeValues = featuresDtoFromDaoList(badgeDaos);
+  const titleDaos = asFeatureDaoList(listing.features_title);
+
+  const status = listing.status === undefined ? undefined : lifecycleCaption(listing.status);
+  const price =
+    listing.price !== undefined && listing.price.length > 0
+      ? `${listing.price} ${listing.currency ?? ""}`.trim()
+      : t(LISTINGS_I18N_KEYS.cardPriceAbsent);
+
+  const favoriteLabel = t(
+    favorite.favorited
+      ? LISTINGS_I18N_KEYS.cardFavoriteRemove
+      : LISTINGS_I18N_KEYS.cardFavoriteAdd
+  );
+
+  return (
+    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <Card
+        size="small"
+        data-testid="listings-card"
+        data-listing-id={listing.id}
+        {...(status !== undefined
+          ? { "data-listing-status": status.status }
+          : {})}
+        cover={
+          <ListingPhoto
+            imageRef={listing.images?.[0]}
+            alt={listing.title ?? String(listing.id)}
+            style={{ aspectRatio: "4 / 3" }}
+          />
+        }
+      >
+        <Flex vertical gap={4}>
+          {props.badge}
+
+          <Typography.Text strong data-testid="listings-card-price">
+            {price}
+          </Typography.Text>
+
+          <Typography.Text ellipsis data-testid="listings-card-title">
+            {listing.title ?? ""}
+          </Typography.Text>
+
+          {/* The title features are a stored projection too — the seller's
+              "1.5 TB, black" line, already ordered by the server. */}
+          {titleDaos.length > 0 ? (
+            <Typography.Text type="secondary" ellipsis>
+              <FeatureBadges
+                features={featuresFromDaoList(titleDaos)
+                  .map((view) => view.feature)}
+                values={featuresDtoFromDaoList(titleDaos)}
+              />
+            </Typography.Text>
+          ) : null}
+
+          {badgeFeatures.length > 0 ? (
+            <FeatureBadges
+              features={badgeFeatures.map((view) => view.feature)}
+              values={badgeValues}
+            />
+          ) : null}
+
+          {listing.location_label !== undefined &&
+          listing.location_label.length > 0 ? (
+            <Typography.Text type="secondary" data-testid="listings-card-location">
+              {listing.location_label}
+            </Typography.Text>
+          ) : 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}
+
+            {props.showFavorite === false ? null : (
+              <Tooltip
+                title={
+                  favorite.gate.available
+                    ? favoriteLabel
+                    : t(favorite.gate.block.code, favorite.gate.block.params)
+                }
+              >
+                {/* A disabled antd Button swallows pointer events, so the
+                    tooltip needs the wrapper to hear them — which is also
+                    what makes the REASON reachable by keyboard. */}
+                <span data-testid="listings-card-favorite-wrap">
+                  <Button
+                    size="small"
+                    disabled={!favorite.gate.available}
+                    aria-label={favoriteLabel}
+                    aria-pressed={favorite.favorited}
+                    data-testid="listings-card-favorite"
+                    data-favorited={String(favorite.favorited)}
+                    data-analytics="none"
+                    data-analytics-reason="business action — host app wraps with its own tracked()"
+                    onClick={favorite.toggle}
+                    icon={<HeartIcon filled={favorite.favorited} />}
+                  />
+                </span>
+              </Tooltip>
+            )}
+          </Flex>
+        </Flex>
+      </Card>
+    </ListingsSkinTheme>
+  );
+}

package/src/default/ListingComposerPage.tsx

@@ -0,0 +1,466 @@
+/**
+ * `<ListingComposerPage>` — the submission screen.
+ *
+ * Four 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   `categorySlot`  — the container's `<CategoryPickerField>`
+ *   details    `features`      — the schema, drawn by `<FeatureFields>` (L0)
+ *   photos     `gallerySlot`   — the container's `<MediaGalleryField>`, whose
+ *                                bag is handed to the composer as `images`
+ *   the draft  this pair
+ *
+ * ── 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
+ * point: "sign in", "choose a category", "we could not load what this
+ * 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.
+ */
+import type { ReactElement, ReactNode } from "react";
+import {
+  Alert,
+  Button,
+  Checkbox,
+  Divider,
+  Flex,
+  Form,
+  Input,
+  InputNumber,
+  Space,
+  Typography,
+} from "antd";
+import { useDescribeFlowError, useT } from "@stapel/core";
+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 { ListingImagesBag } from "../headless/ListingComposer.js";
+import {
+  CATEGORY_FIELD,
+  DESCRIPTION_FIELD,
+  IMAGES_FIELD,
+  PRICE_FIELD,
+  TITLE_FIELD,
+  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";
+
+export interface ListingComposerPageProps extends ThemeModeProp {
+  /** Editing an existing listing; absent for a new one. */
+  readonly listingId?: number;
+  /** The chosen category's features — from `@stapel/categories-react` via the
+   * container (L2 pairs do not import each other). */
+  readonly features: readonly FeatureDef[];
+  readonly featuresLoading?: boolean;
+  readonly featuresError?: unknown;
+  /** The category chooser. A slot for the same reason. */
+  readonly categorySlot?: ReactNode;
+  /** The photo grid. Its bag is what `images` carries. */
+  readonly gallerySlot?: ReactNode;
+  /** `useUploadQueue()`'s bag from `@stapel/cdn-react` — `refs` becomes
+   * `images_draft`, `settled` gates the submit. */
+  readonly images?: ListingImagesBag;
+  readonly onPublished?: (listingId: number) => void;
+}
+
+export function ListingComposerPage(
+  props: ListingComposerPageProps
+): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const bag = useListingComposer({
+    ...(props.listingId !== undefined ? { listingId: props.listingId } : {}),
+    features: props.features,
+    ...(props.featuresLoading !== undefined
+      ? { featuresLoading: props.featuresLoading }
+      : {}),
+    ...(props.featuresError !== undefined
+      ? { featuresError: props.featuresError }
+      : {}),
+    editorTypes: BUILTIN_VALUE_EDITOR_TYPES,
+    ...(props.images !== undefined ? { images: props.images } : {}),
+    ...(props.onPublished !== undefined
+      ? {
+          // `listing_id` comes back in the response, so the callback never
+          // has to reach for a piece of state that may be one render behind.
+          onPublished: (response) => {
+            props.onPublished?.(response.listing_id);
+          },
+        }
+      : {}),
+  });
+
+  /** Spread onto a `Form.Item`: the two props exist only when there IS a
+   * refusal, which is what `exactOptionalPropertyTypes` asks for and what
+   * keeps a clean field from rendering an empty help line. */
+  const errorOf = (
+    field: string
+  ): { help: ReactNode; validateStatus: "error" } | Record<string, never> => {
+    const error = bag.fieldErrors[field];
+    if (error === undefined) return {};
+    return { help: describe(error).message, validateStatus: "error" };
+  };
+
+  const publishLabel = t(
+    bag.isLiveEdit
+      ? LISTINGS_I18N_KEYS.composeRepublish
+      : LISTINGS_I18N_KEYS.composePublish
+  );
+
+  return (
+    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <Flex vertical gap={16} data-testid="listings-composer" data-stage={bag.stage}>
+        <Typography.Title level={3}>
+          {t(
+            props.listingId === undefined
+              ? LISTINGS_I18N_KEYS.composeNewTitle
+              : LISTINGS_I18N_KEYS.composeEditTitle
+          )}
+        </Typography.Title>
+
+        {/* stapel-listings 0.6.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 ? (
+          <Alert
+            type="warning"
+            showIcon
+            data-testid="listings-composer-draft-unreadable"
+            message={t(LISTINGS_I18N_KEYS.composeBlockedNoDraft)}
+          />
+        ) : null}
+
+        {bag.outcome !== undefined ? (
+          <Alert
+            type="success"
+            showIcon
+            data-testid="listings-composer-published"
+            data-outcome={bag.outcome}
+            message={t(
+              bag.outcome === "live_edit_under_review"
+                ? LISTINGS_I18N_KEYS.composePublishedLive
+                : LISTINGS_I18N_KEYS.composePublishedFirst
+            )}
+          />
+        ) : null}
+
+        <Form layout="vertical" data-testid="listings-composer-form">
+          <Form.Item
+            label={t(LISTINGS_I18N_KEYS.composeCategory)}
+            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);
+                }}
+              />
+            )}
+          </Form.Item>
+
+          {bag.droppedOnCategoryChange.length > 0 ? (
+            <Alert
+              type="info"
+              showIcon
+              data-testid="listings-composer-dropped"
+              message={t(LISTINGS_I18N_KEYS.composeCategoryChangedDropped, {
+                count: bag.droppedOnCategoryChange.length,
+              })}
+            />
+          ) : null}
+
+          <Form.Item
+            label={t(LISTINGS_I18N_KEYS.composeTitleLabel)}
+            {...errorOf(TITLE_FIELD)}
+          >
+            <Input
+              value={bag.values.title}
+              aria-label={t(LISTINGS_I18N_KEYS.composeTitleLabel)}
+              data-testid="listings-composer-title"
+              onChange={(event) => {
+                bag.setValue("title", event.target.value);
+              }}
+              onBlur={bag.save}
+            />
+          </Form.Item>
+
+          <Form.Item
+            label={t(LISTINGS_I18N_KEYS.composeDescriptionLabel)}
+            {...errorOf(DESCRIPTION_FIELD)}
+          >
+            <Input.TextArea
+              rows={5}
+              value={bag.values.description}
+              aria-label={t(LISTINGS_I18N_KEYS.composeDescriptionLabel)}
+              data-testid="listings-composer-description"
+              onChange={(event) => {
+                bag.setValue("description", event.target.value);
+              }}
+              onBlur={bag.save}
+            />
+          </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)}>
+            <Input
+              value={bag.values.location.locationLabel}
+              aria-label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}
+              data-testid="listings-composer-location"
+              onChange={(event) => {
+                bag.setLocation({
+                  ...bag.values.location,
+                  locationLabel: 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>
+
+          <Divider />
+
+          <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>
+          ) : null}
+
+          <Divider />
+
+          <Typography.Title level={5}>
+            {t(LISTINGS_I18N_KEYS.composeDetails)}
+          </Typography.Title>
+          {props.featuresError !== undefined ? (
+            <Alert
+              type="error"
+              showIcon
+              data-testid="listings-composer-features-failed"
+              message={t(LISTINGS_I18N_KEYS.composeDetailsFailed)}
+            />
+          ) : props.featuresLoading === true ? (
+            <Typography.Text type="secondary" data-testid="listings-composer-features-loading">
+              {t(LISTINGS_I18N_KEYS.composeDetailsLoading)}
+            </Typography.Text>
+          ) : props.features.length === 0 ? (
+            <Typography.Text type="secondary" data-testid="listings-composer-features-empty">
+              {t(LISTINGS_I18N_KEYS.composeDetailsEmpty)}
+            </Typography.Text>
+          ) : (
+            <FeatureFields
+              features={props.features}
+              values={bag.values.features}
+              errors={bag.fieldErrors}
+              disabled={bag.publishing}
+              onChange={bag.setFeature}
+            />
+          )}
+
+          <Divider />
+
+          <Form.Item>
+            <Checkbox
+              checked={bag.values.countable}
+              data-testid="listings-composer-countable"
+              onChange={(event) => {
+                bag.setValue("countable", event.target.checked);
+              }}
+            >
+              {t(LISTINGS_I18N_KEYS.composeCountable)}
+            </Checkbox>
+          </Form.Item>
+
+          {bag.values.countable ? (
+            <Form.Item label={t(LISTINGS_I18N_KEYS.composeStock)}>
+              <InputNumber
+                min={0}
+                value={bag.values.stockQuantity}
+                aria-label={t(LISTINGS_I18N_KEYS.composeStock)}
+                data-testid="listings-composer-stock"
+                onChange={(value) => {
+                  bag.setValue("stockQuantity", value ?? null);
+                }}
+              />
+            </Form.Item>
+          ) : null}
+
+          <Form.Item>
+            <Checkbox
+              checked={bag.values.autoRepublish}
+              data-testid="listings-composer-auto-republish"
+              onChange={(event) => {
+                bag.setValue("autoRepublish", event.target.checked);
+              }}
+            >
+              {t(LISTINGS_I18N_KEYS.composeAutoRepublish)}
+            </Checkbox>
+          </Form.Item>
+        </Form>
+
+        {bag.refusal?.kind === "invalid_draft" ? (
+          <Alert
+            type="error"
+            showIcon
+            data-testid="listings-composer-invalid"
+            message={t(LISTINGS_I18N_KEYS.composeInvalidSummary, {
+              count: failedResults(bag.refusal.batch).length,
+            })}
+          />
+        ) : null}
+
+        {bag.refusal?.kind === "error" ? (
+          <ErrorAlert
+            testId="listings-composer-error"
+            error={describe({
+              code: bag.refusal.error.code,
+              params: bag.refusal.error.params,
+              status: bag.refusal.error.status,
+              message: bag.refusal.error.message,
+              language: bag.refusal.error.language,
+            })}
+          />
+        ) : null}
+
+        {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,
+            })}
+          />
+        ) : 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
+            type="primary"
+            disabled={!bag.publishGate.available}
+            loading={bag.publishing}
+            data-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>
+
+          {bag.saved ? (
+            <Typography.Text type="success" data-testid="listings-composer-saved">
+              {t(LISTINGS_I18N_KEYS.composeSaved)}
+            </Typography.Text>
+          ) : null}
+        </Space>
+
+        {!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}
+      </Flex>
+    </ListingsSkinTheme>
+  );
+}