@stapel/listings-react 0.1.0

package/src/default/ListingDetailPane.tsx

@@ -0,0 +1,271 @@
+/**
+ * `<ListingDetailPane>` — the listing page.
+ *
+ * Four distinct absences, four distinct sentences, and the whole point of the
+ * component is that none of them collapses into another:
+ *
+ *   loading            — we are asking
+ *   failed             — we could not ask   (retry, never "nothing here")
+ *   not found          — no listing ever had this id
+ *   removed            — one did, and it is gone (the AllowAny status probe
+ *                        is the only read that can still say so)
+ *
+ * On top of that, a listing that IS returned may still not be on sale: the
+ * detail endpoint has no `published()` filter, so a draft answers 200 to
+ * anyone holding the id. The pane says which side of that it is on rather
+ * than dressing a draft up as a shop page.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Alert, Button, Descriptions, Divider, Flex, Space, Spin, Typography } from "antd";
+import { matchLoad, useDescribeFlowError, useT, useI18n } from "@stapel/core";
+import { FeatureValueList } from "@stapel/attributes-react/default";
+import { formatFeatureValue } from "@stapel/attributes-react";
+import { useListingDetail } from "../headless/ListingDetail.js";
+import { asFeatureDaoList, featuresDtoFromDaoList } from "../model/features.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { HeartIcon } from "./icons.js";
+import { ListingPhoto } from "./ListingPhoto.js";
+import { ListingStatusBlock } from "./StatusTags.js";
+import { ListingsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+export interface ListingDetailPaneProps extends ThemeModeProp {
+  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
+   * person it concerns. */
+  readonly viewerId?: string;
+  /** Slots the container fills: "message the seller" (chat-react), the
+   * seller's profile link, reviews. Cross-pair navigation is the container's
+   * job (spec §6.2 item 5), so this pair takes nodes rather than routes. */
+  readonly actions?: ReactNode;
+  readonly footer?: ReactNode;
+}
+
+export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
+  const t = useT();
+  const { locale } = useI18n();
+  const describe = useDescribeFlowError();
+  const bag = useListingDetail(
+    props.id,
+    props.viewerId !== undefined ? { viewerId: props.viewerId } : {}
+  );
+
+  return (
+    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <Flex vertical gap={16} data-testid="listings-detail">
+        {bag.removed ? (
+          <Alert
+            type="warning"
+            showIcon
+            data-testid="listings-detail-removed"
+            message={t(LISTINGS_I18N_KEYS.detailRemoved)}
+          />
+        ) : null}
+
+        {matchLoad(bag.state, {
+          loading: () => (
+            <Flex justify="center" data-testid="listings-detail-loading">
+              <Spin aria-label={t(LISTINGS_I18N_KEYS.detailLoading)} />
+            </Flex>
+          ),
+          failed: () =>
+            bag.removed ? null : (
+              <ErrorAlert
+                testId="listings-detail-error"
+                error={describe({
+                  code: bag.notFound
+                    ? LISTINGS_I18N_KEYS.detailNotFound
+                    : LISTINGS_I18N_KEYS.detailLoadFailed,
+                  params: {},
+                  status: 0,
+                  message: undefined,
+                  language: undefined,
+                })}
+                action={
+                  <Button
+                    size="small"
+                    data-analytics="none"
+                    data-analytics-reason="retrying a read the person already asked for; not a business action"
+                    onClick={bag.refetch}
+                  >
+                    {t(LISTINGS_I18N_KEYS.detailRetry)}
+                  </Button>
+                }
+              />
+            ),
+          ready: (listing) => (
+            <>
+              {/* The moderation axis is the OWNER's business and nobody
+                  else's: a buyer has no use for "changes under review", and
+                  showing a stranger that a listing was refused would leak a
+                  verdict about someone else's content. */}
+              {bag.viewerIsOwner === true && bag.status !== undefined ? (
+                <Flex vertical gap={8} data-testid="listings-detail-owner-view">
+                  <ListingStatusBlock status={bag.status} />
+                  {!bag.publiclyVisible ? (
+                    <Alert
+                      type="info"
+                      showIcon
+                      message={t(LISTINGS_I18N_KEYS.detailOwnerOnlyView)}
+                    />
+                  ) : null}
+                </Flex>
+              ) : null}
+
+              {bag.viewerIsOwner !== true && !bag.publiclyVisible ? (
+                <Alert
+                  type="warning"
+                  showIcon
+                  data-testid="listings-detail-not-published"
+                  message={t(LISTINGS_I18N_KEYS.detailNotPublished)}
+                />
+              ) : null}
+
+              <Flex gap={16} wrap>
+                {bag.images.length === 0 ? (
+                  <ListingPhoto
+                    imageRef={undefined}
+                    alt={listing.title ?? String(listing.id)}
+                    style={{ width: 320, aspectRatio: "4 / 3" }}
+                  />
+                ) : (
+                  bag.images.map((ref, index) => (
+                    <ListingPhoto
+                      key={ref}
+                      imageRef={ref}
+                      alt={t(LISTINGS_I18N_KEYS.detailPhotoAlt, {
+                        index: index + 1,
+                        total: bag.images.length,
+                      })}
+                      style={{ width: 320, aspectRatio: "4 / 3" }}
+                    />
+                  ))
+                )}
+              </Flex>
+
+              <Typography.Title level={3} data-testid="listings-detail-title">
+                {listing.title ?? ""}
+              </Typography.Title>
+
+              {/* The `show_at_title` projection, formatted from the stored
+                  DAOs — no category read needed (see model/features.ts). */}
+              {bag.titleFeatures.length > 0 ? (
+                <Typography.Text type="secondary" data-testid="listings-detail-title-features">
+                  {bag.titleFeatures
+                    .map((view) =>
+                      formatFeatureValue(view.feature, view.value, { t, locale })
+                    )
+                    .filter((text): text is string => text !== undefined)
+                    .join(" · ")}
+                </Typography.Text>
+              ) : null}
+
+              <Typography.Title level={4} data-testid="listings-detail-price">
+                {listing.price !== undefined && listing.price.length > 0
+                  ? `${listing.price} ${listing.currency ?? ""}`.trim()
+                  : t(LISTINGS_I18N_KEYS.cardPriceAbsent)}
+              </Typography.Title>
+
+              <Space wrap>
+                <Button
+                  disabled={!bag.favoriteGate.available}
+                  aria-label={t(
+                    bag.isFavorited === true
+                      ? LISTINGS_I18N_KEYS.cardFavoriteRemove
+                      : LISTINGS_I18N_KEYS.cardFavoriteAdd
+                  )}
+                  aria-pressed={bag.isFavorited === true}
+                  icon={<HeartIcon filled={bag.isFavorited === true} />}
+                  data-testid="listings-detail-favorite"
+                  data-analytics="none"
+                  data-analytics-reason="business action — host app wraps with its own tracked()"
+                  onClick={bag.toggleFavorite}
+                >
+                  {t(
+                    bag.isFavorited === true
+                      ? LISTINGS_I18N_KEYS.cardFavoriteRemove
+                      : LISTINGS_I18N_KEYS.cardFavoriteAdd
+                  )}
+                </Button>
+                {props.actions}
+              </Space>
+
+              {/* A switched-off control that cannot say why is the one shape
+                  ActionAvailability makes unwritable — so the reason is
+                  rendered, not implied by the disabled attribute. */}
+              {!bag.favoriteGate.available ? (
+                <Typography.Text
+                  type="secondary"
+                  data-testid="listings-detail-favorite-blocked"
+                >
+                  {t(
+                    bag.favoriteGate.block.code,
+                    bag.favoriteGate.block.params
+                  )}
+                </Typography.Text>
+              ) : null}
+
+              <Divider />
+
+              <Typography.Title level={5}>
+                {t(LISTINGS_I18N_KEYS.detailDescription)}
+              </Typography.Title>
+              <Typography.Paragraph data-testid="listings-detail-description">
+                {listing.description ?? ""}
+              </Typography.Paragraph>
+
+              <Typography.Title level={5}>
+                {t(LISTINGS_I18N_KEYS.detailSpecs)}
+              </Typography.Title>
+              {bag.features.length === 0 ? (
+                <Typography.Text type="secondary" data-testid="listings-detail-no-specs">
+                  {t(LISTINGS_I18N_KEYS.detailNoSpecs)}
+                </Typography.Text>
+              ) : (
+                <FeatureValueList
+                  features={bag.features.map((view) => view.feature)}
+                  values={featuresDtoFromDaoList(
+                    asFeatureDaoList(listing.features)
+                  )}
+                />
+              )}
+
+              {/* Counted, not rounded to zero: a stored attribute this build
+                  cannot key is a gap in what the buyer is being told. */}
+              {bag.unreadableFeatures > 0 ? (
+                <Alert
+                  type="warning"
+                  showIcon
+                  data-testid="listings-detail-unreadable"
+                  message={t(LISTINGS_I18N_KEYS.detailUnreadableFeatures, {
+                    count: bag.unreadableFeatures,
+                  })}
+                />
+              ) : null}
+
+              <Descriptions size="small" column={1}>
+                {listing.stock_quantity != null ? (
+                  <Descriptions.Item label={t(LISTINGS_I18N_KEYS.detailStock)}>
+                    {listing.stock_quantity}
+                  </Descriptions.Item>
+                ) : null}
+                {listing.location_label !== undefined &&
+                listing.location_label.length > 0 ? (
+                  <Descriptions.Item
+                    label={t(LISTINGS_I18N_KEYS.composeLocationLabel)}
+                  >
+                    {listing.location_label}
+                  </Descriptions.Item>
+                ) : null}
+              </Descriptions>
+
+              {props.footer}
+            </>
+          ),
+        })}
+      </Flex>
+    </ListingsSkinTheme>
+  );
+}

package/src/default/ListingPhoto.tsx

@@ -0,0 +1,62 @@
+/**
+ * A stored CDN reference, drawn — or the reason it cannot be.
+ *
+ * `Listing.images` carries opaque `<type>/<hash>` strings and no contract in
+ * this fleet resolves a stranger's reference (`model/runtime.ts` argues it at
+ * length). So this component asks the runtime's `resolveImage`, and when
+ * there is no resolver — or the resolver has nothing for this reference — it
+ * says so instead of emitting a broken `<img>`. An empty grey box that never
+ * loads teaches a person nothing; a sentence gets the wiring fixed.
+ *
+ * When the resolver DOES answer, `@stapel/image`'s `<Image>` takes over: it
+ * measures the slot, picks the variant tier that fits, blur-ups from
+ * `preview_b64` and never downgrades on a re-measure. None of that logic
+ * belongs here — it is why `@stapel/image` exists.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import { Empty } from "antd";
+import { Image } from "@stapel/image";
+import { useT } from "@stapel/core";
+import { useListingsRuntime } from "../model/context.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+
+export interface ListingPhotoProps {
+  /** The stored reference, or `undefined` for a listing with no photos. */
+  readonly imageRef: string | undefined;
+  /** Alt text — required, and the caller has the context to write it. */
+  readonly alt: string;
+  readonly style?: CSSProperties;
+}
+
+export function ListingPhoto(props: ListingPhotoProps): ReactElement {
+  const t = useT();
+  const runtime = useListingsRuntime();
+  const meta =
+    props.imageRef === undefined || runtime.resolveImage === undefined
+      ? undefined
+      : runtime.resolveImage(props.imageRef);
+
+  if (meta === undefined) {
+    return (
+      <Empty
+        image={Empty.PRESENTED_IMAGE_SIMPLE}
+        data-testid="listings-photo-absent"
+        description={t(
+          props.imageRef === undefined
+            ? LISTINGS_I18N_KEYS.cardNoPhoto
+            : LISTINGS_I18N_KEYS.cardPhotoUnavailable
+        )}
+        {...(props.style ? { style: props.style } : {})}
+      />
+    );
+  }
+
+  return (
+    <Image
+      meta={meta}
+      alt={props.alt}
+      data-testid="listings-photo"
+      {...(props.style ? { style: props.style } : {})}
+    />
+  );
+}

package/src/default/MyListingsPane.tsx

@@ -0,0 +1,333 @@
+/**
+ * `<MyListingsPane>` — the seller's dashboard.
+ *
+ * Three counts that are real, and rows that may not be: stapel-listings 0.6.1
+ * has no owner-scoped list endpoint (`headless/MyListings.tsx` argues it in
+ * full), so the rows come from an injected source and the pane NAMES the gap
+ * when there is none. The counters are shown either way, because they are the
+ * one thing the contract can actually answer.
+ *
+ * Each row carries both axes. "Published" and "changes under review" appear
+ * beside each other, which is the entire reason `model/status.ts` exists: a
+ * dashboard that derived one from the other would tell a seller their live
+ * listing is offline, or never tell them their edit is being screened.
+ */
+import type { ReactElement } from "react";
+import {
+  Alert,
+  Badge,
+  Button,
+  Empty,
+  Flex,
+  List,
+  Space,
+  Spin,
+  Tabs,
+  Tooltip,
+  Typography,
+} from "antd";
+import { matchList, matchLoad, useDescribeFlowError, useT } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import type { ListingCard as ListingCardData } from "../api/types.js";
+import { useMyListings } from "../headless/MyListings.js";
+import type { MyListingsSource } from "../model/mineSource.js";
+import { useListingActions } from "../headless/ListingActions.js";
+import { listingStatusView } from "../model/status.js";
+import type { MyListingsTab } from "../model/status.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+import { ListingStatusBlock } from "./StatusTags.js";
+import { ListingsSkinTheme } from "./theme.js";
+import type { ThemeModeProp } from "./types.js";
+
+const TAB_LABEL: Readonly<Record<MyListingsTab, string>> = {
+  active: LISTINGS_I18N_KEYS.mineTabActive,
+  drafts: LISTINGS_I18N_KEYS.mineTabDrafts,
+  archived: LISTINGS_I18N_KEYS.mineTabArchived,
+};
+
+/** A control plus the sentence that explains it when it is off. Written once
+ * here because this pane has six of them and a grey button with no reason is
+ * the one shape `ActionAvailability` exists to make impossible. */
+function GatedButton(props: {
+  gate: ActionAvailability;
+  label: string;
+  testId: string;
+  onClick: () => void;
+  danger?: boolean;
+  /** The call sites mark themselves `data-analytics="none"` with a
+   * `passthrough` reason (the convention `stapel/clickable-needs-event`
+   * documents for a forwarding component); the real click point is the antd
+   * button below, which declares its own outcome. */
+  "data-analytics"?: string;
+  "data-analytics-reason"?: string;
+}): ReactElement {
+  const t = useT();
+  return (
+    <Tooltip
+      title={
+        props.gate.available
+          ? props.label
+          : t(props.gate.block.code, props.gate.block.params)
+      }
+    >
+      <span>
+        <Button
+          size="small"
+          danger={props.danger === true}
+          disabled={!props.gate.available}
+          data-testid={props.testId}
+          data-analytics="none"
+          data-analytics-reason="business action — host app wraps with its own tracked()"
+          onClick={props.onClick}
+        >
+          {props.label}
+        </Button>
+      </span>
+    </Tooltip>
+  );
+}
+
+function MyListingRow(props: {
+  listing: ListingCardData;
+  onEdit?: (id: number) => void;
+}): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const actions = useListingActions(props.listing.id, props.listing.status);
+  // The card list carries `status` but NOT `moderation_status`
+  // (`ListingCardSerializer` omits it), so a row shows the moderation axis
+  // only through the one thing the projection does say. Pending is the
+  // honest default for the notice table's second argument here: it is the
+  // value that produces a note only when the lifecycle also implies one.
+  const status =
+    props.listing.status === undefined
+      ? undefined
+      : listingStatusView(props.listing.status, "approved");
+
+  return (
+    <List.Item
+      data-testid="listings-mine-row"
+      data-listing-id={props.listing.id}
+      actions={[
+        <GatedButton
+          key="edit"
+          data-analytics="none"
+          data-analytics-reason="passthrough — GatedButton owns the real click point"
+          gate={{ available: true }}
+          label={t(LISTINGS_I18N_KEYS.mineEdit)}
+          testId="listings-mine-edit"
+          onClick={() => {
+            props.onEdit?.(props.listing.id);
+          }}
+        />,
+        <GatedButton
+          key="complete"
+          data-analytics="none"
+          data-analytics-reason="passthrough — GatedButton owns the real click point"
+          gate={actions.complete}
+          label={t(LISTINGS_I18N_KEYS.mineComplete)}
+          testId="listings-mine-complete"
+          onClick={actions.doComplete}
+        />,
+        <GatedButton
+          key="archive"
+          data-analytics="none"
+          data-analytics-reason="passthrough — GatedButton owns the real click point"
+          gate={actions.archive}
+          label={t(LISTINGS_I18N_KEYS.mineArchive)}
+          testId="listings-mine-archive"
+          onClick={actions.doArchive}
+        />,
+        <GatedButton
+          key="delete"
+          data-analytics="none"
+          data-analytics-reason="passthrough — GatedButton owns the real click point"
+          danger
+          gate={actions.remove}
+          label={t(LISTINGS_I18N_KEYS.mineDelete)}
+          testId="listings-mine-delete"
+          onClick={actions.doRemove}
+        />,
+      ]}
+    >
+      <List.Item.Meta
+        title={props.listing.title ?? String(props.listing.id)}
+        description={
+          <Flex vertical gap={4}>
+            {status !== undefined ? <ListingStatusBlock status={status} /> : null}
+            {actions.error !== undefined && actions.error !== null ? (
+              <ErrorAlert
+                testId="listings-mine-action-error"
+                error={describe({
+                  code: LISTINGS_I18N_KEYS.unknownError,
+                  params: {},
+                  status: 0,
+                  message: undefined,
+                  language: undefined,
+                })}
+              />
+            ) : null}
+          </Flex>
+        }
+      />
+    </List.Item>
+  );
+}
+
+export interface MyListingsPaneProps extends ThemeModeProp {
+  /** How the host gets the caller's own rows. Absent: the pane says the
+   * contract cannot answer, and still shows the counts. */
+  readonly source?: MyListingsSource;
+  readonly onEdit?: (id: number) => void;
+}
+
+export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
+  const t = useT();
+  const describe = useDescribeFlowError();
+  const bag = useMyListings(
+    props.source !== undefined ? { source: props.source } : {}
+  );
+
+  return (
+    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
+      <Flex vertical gap={16} data-testid="listings-mine">
+        <Typography.Title level={3}>
+          {t(LISTINGS_I18N_KEYS.mineTitle)}
+        </Typography.Title>
+
+        {!bag.gate.available ? (
+          <Alert
+            type="info"
+            showIcon
+            data-testid="listings-mine-blocked"
+            message={t(bag.gate.block.code, bag.gate.block.params)}
+          />
+        ) : null}
+
+        <Tabs
+          activeKey={bag.tab}
+          data-testid="listings-mine-tabs"
+          onChange={(key) => {
+            bag.setTab(key as MyListingsTab);
+          }}
+          items={bag.tabs.map((tab) => ({
+            key: tab,
+            label: (
+              <Space size={6}>
+                {t(TAB_LABEL[tab])}
+                {matchLoad(bag.counters, {
+                  loading: () => null,
+                  // A count we could not fetch is not zero. The badge is
+                  // simply absent and the failure is stated once, below.
+                  failed: () => null,
+                  ready: (counters) => (
+                    <Badge
+                      count={counters[tab]}
+                      showZero
+                      data-testid={`listings-mine-count-${tab}`}
+                    />
+                  ),
+                })}
+              </Space>
+            ),
+          }))}
+        />
+
+        {matchLoad(bag.counters, {
+          loading: () => null,
+          failed: () => (
+            <Typography.Text type="secondary" data-testid="listings-mine-counters-failed">
+              {t(LISTINGS_I18N_KEYS.mineCountersFailed)}
+            </Typography.Text>
+          ),
+          ready: () => null,
+        })}
+
+        {matchList(bag.rows, {
+          loading: () => (
+            <Flex justify="center" data-testid="listings-mine-loading">
+              <Spin aria-label={t(LISTINGS_I18N_KEYS.mineLoading)} />
+            </Flex>
+          ),
+          failed: () => (
+            <ErrorAlert
+              testId="listings-mine-error"
+              error={describe({
+                code: LISTINGS_I18N_KEYS.mineLoadFailed,
+                params: {},
+                status: 0,
+                message: undefined,
+                language: undefined,
+              })}
+              action={
+                <Button
+                  size="small"
+                  data-analytics="none"
+                  data-analytics-reason="retrying a read the person already asked for; not a business action"
+                  onClick={bag.refetch}
+                >
+                  {t(LISTINGS_I18N_KEYS.mineRetry)}
+                </Button>
+              }
+            />
+          ),
+          empty: () => (
+            <Empty
+              data-testid="listings-mine-empty"
+              description={t(LISTINGS_I18N_KEYS.mineEmpty)}
+            />
+          ),
+          ready: (rows) => (
+            <List
+              dataSource={[...rows]}
+              rowKey={(row) => row.id}
+              renderItem={(row) => (
+                <MyListingRow
+                  listing={row}
+                  {...(props.onEdit !== undefined ? { onEdit: props.onEdit } : {})}
+                />
+              )}
+            />
+          ),
+        })}
+
+        {/* The named gap. `matchList`'s `failed` arm above already renders
+            "we could not load"; this states WHY once, in the pane, because
+            the reason is a property of this deployment and not of this
+            request. */}
+        {props.source === undefined ? (
+          <Alert
+            type="warning"
+            showIcon
+            data-testid="listings-mine-source-missing"
+            message={t(LISTINGS_I18N_KEYS.mineSourceMissing)}
+          />
+        ) : null}
+
+        <Space>
+          <Button
+            size="small"
+            disabled={!bag.prevPage.available}
+            data-testid="listings-mine-prev"
+            data-analytics="none"
+            data-analytics-reason="paging a list the person is already reading; not a business action"
+            onClick={bag.goPrev}
+          >
+            {t(LISTINGS_I18N_KEYS.pagePrev)}
+          </Button>
+          <Button
+            size="small"
+            disabled={!bag.nextPage.available}
+            data-testid="listings-mine-next"
+            data-analytics="none"
+            data-analytics-reason="paging a list the person is already reading; not a business action"
+            onClick={bag.goNext}
+          >
+            {t(LISTINGS_I18N_KEYS.pageNext)}
+          </Button>
+        </Space>
+      </Flex>
+    </ListingsSkinTheme>
+  );
+}