@stapel/listings-react 0.1.0

package/src/headless/ListingDetail.tsx

@@ -0,0 +1,231 @@
+import { useMemo } from "react";
+import type { ReactElement, ReactNode } from "react";
+import {
+  actionAvailable,
+  actionBlocked,
+  errorStatus,
+  firstBlock,
+  loadFailed,
+  loadLoading,
+  loadReady,
+} from "@stapel/core";
+import type { ActionAvailability, LoadState } from "@stapel/core";
+import type {
+  ListingDetail as ListingDetailData,
+  ListingFeatureView,
+  ListingStatusInfo,
+} from "../api/types.js";
+import { useListing, useListingStatus } from "../model/queries.js";
+import { useFavoriteListing } from "../model/mutations.js";
+import { asFeatureDaoList, featuresFromDaoList, unreadableFeatureCount } 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";
+import { useMandateGate } from "./useMandateGate.js";
+
+/**
+ * `images` is `string[] | NULL` on the wire, and the null is the SERVER
+ * saying "this listing has no photos" — not this pair saying "we do not
+ * know". Whether the read landed at all is carried by `state`, one field
+ * over, so collapsing the null here loses nothing: a named constant makes
+ * that argument visible where a bare `?? []` would look like the flattening
+ * `no-flattened-load-state` bans.
+ */
+const NO_IMAGES: readonly string[] = [];
+
+/**
+ * Everything a listing page renders, with the two absences it must be able to
+ * tell apart.
+ *
+ * ── Why a second read runs beside the detail ───────────────────────────────
+ *
+ * `GET /listings/{pk}/` reads `Listing.objects`, which excludes soft-deleted
+ * rows: a removed listing answers 404, and a 404 is also what a made-up id
+ * answers. `GET /listings/{pk}/status/` reads `Listing.all_objects` and is
+ * `AllowAny`, so it still answers for the removed one. Running both is what
+ * turns "there is no listing at this address" and "this listing was removed"
+ * into two different sentences — and the second is the one a person following
+ * a stale link actually needs.
+ *
+ * The probe is not a fallback fired after a failure: it runs in parallel, so
+ * the page resolves in one round trip rather than two sequential ones.
+ *
+ * ── Visibility is reported, not assumed ────────────────────────────────────
+ *
+ * The detail endpoint has NO `published()` filter on its queryset, so a draft
+ * and a taken-down listing both answer 200 to anyone holding the id. The bag
+ * therefore carries `publiclyVisible` (computed from `status`, the one field
+ * that decides it) and `viewerIsOwner`, and a skin says which of the two
+ * situations it is in. Rendering a draft as a live shop page would be the
+ * pair repeating the server's omission instead of covering it.
+ */
+export interface ListingDetailBag {
+  readonly id: number;
+  readonly state: LoadState<ListingDetailData>;
+  /** The status probe, which answers for rows the detail cannot see. */
+  readonly statusState: LoadState<ListingStatusInfo>;
+  /** True when the detail 404s AND the probe says the row is soft-deleted —
+   * i.e. it existed and is gone, rather than never having existed. */
+  readonly removed: boolean;
+  /** The detail 404s and the probe finds nothing either. */
+  readonly notFound: boolean;
+  /** Both axes plus the sentence that comes out of the pair of them. */
+  readonly status: ListingStatusView | undefined;
+  readonly publiclyVisible: boolean;
+  /** Whether the person reading this is the owner, when both the probe and
+   * the viewer's id are known. `undefined` means "we did not ask" — a public
+   * page has no reason to. */
+  readonly viewerIsOwner: boolean | undefined;
+  /** The ordered specs table. */
+  readonly features: readonly ListingFeatureView[];
+  /** The `show_at_title` subset — what a heading appends. */
+  readonly titleFeatures: readonly ListingFeatureView[];
+  /** The `show_as_badge` subset — what a card shows. */
+  readonly badgeFeatures: readonly ListingFeatureView[];
+  /** Stored rows this build could not key. Reported, never rounded to zero. */
+  readonly unreadableFeatures: number;
+  /** Ordered CDN references. Resolving one to an image is the runtime's job
+   * (`resolveImage`), because no contract in this fleet resolves a
+   * stranger's reference — see `model/runtime.ts`. */
+  readonly images: readonly string[];
+  readonly isFavorited: boolean | undefined;
+  /** Saving a favourite needs a mandate; the block says which of the four
+   * reasons applies. */
+  readonly favoriteGate: ActionAvailability;
+  toggleFavorite(): void;
+  readonly favoriteInFlight: boolean;
+  refetch(): void;
+}
+
+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;
+}
+
+export function useListingDetail(
+  id: number,
+  options: UseListingDetailOptions = {}
+): ListingDetailBag {
+  const detail = useListing(id);
+  const probe = useListingStatus(id);
+  const favorite = useFavoriteListing();
+  const mandate = useMandateGate();
+
+  const state: LoadState<ListingDetailData> =
+    detail.status === "error"
+      ? loadFailed(detail.error)
+      : detail.data !== undefined
+        ? loadReady(detail.data)
+        : loadLoading();
+
+  const statusState: LoadState<ListingStatusInfo> =
+    probe.status === "error"
+      ? loadFailed(probe.error)
+      : probe.data !== undefined
+        ? loadReady(probe.data)
+        : loadLoading();
+
+  const detailIs404 =
+    detail.status === "error" && errorStatus(detail.error) === 404;
+  const removed = detailIs404 && probe.data?.is_deleted === true;
+  const notFound = detailIs404 && !removed && probe.status === "error";
+
+  const status: ListingStatusView | undefined = useMemo(() => {
+    if (detail.data !== undefined) {
+      return listingStatusView(
+        detail.data.status ?? "draft",
+        detail.data.moderation_status ?? "pending"
+      );
+    }
+    // The probe still knows both axes for a row the detail cannot return —
+    // `moderation_status` arrives as a bare string there, so it is narrowed
+    // by the same table rather than trusted.
+    if (probe.data !== undefined) {
+      const moderation = probe.data.moderation_status;
+      return listingStatusView(
+        probe.data.status,
+        moderation === "approved" ||
+          moderation === "rejected" ||
+          moderation === "needs_review"
+          ? moderation
+          : "pending"
+      );
+    }
+    return undefined;
+  }, [detail.data, probe.data]);
+
+  const owner = detail.data?.owner ?? probe.data?.owner_id;
+  const viewerIsOwner =
+    options.viewerId === undefined || owner === undefined
+      ? undefined
+      : owner === options.viewerId;
+
+  const features = useMemo(
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features)),
+    [detail.data]
+  );
+  const titleFeatures = useMemo(
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_title)),
+    [detail.data]
+  );
+  const badgeFeatures = useMemo(
+    () => featuresFromDaoList(asFeatureDaoList(detail.data?.features_badges)),
+    [detail.data]
+  );
+
+  const isFavorited = detail.data?.is_favorited ?? undefined;
+
+  const favoriteGate = firstBlock(
+    mandate,
+    favorite.isPending
+      ? actionBlocked(LISTINGS_I18N_KEYS.blockedInFlight)
+      : actionAvailable(),
+    detail.data === undefined
+      ? actionBlocked(LISTINGS_I18N_KEYS.detailLoading)
+      : actionAvailable()
+  );
+
+  return {
+    id,
+    state,
+    statusState,
+    removed,
+    notFound,
+    status,
+    publiclyVisible: status?.lifecycle.publiclyVisible ?? false,
+    viewerIsOwner,
+    features,
+    titleFeatures,
+    badgeFeatures,
+    unreadableFeatures: unreadableFeatureCount(
+      asFeatureDaoList(detail.data?.features)
+    ),
+    images: detail.data?.images ?? NO_IMAGES,
+    isFavorited,
+    favoriteGate,
+    toggleFavorite: () => {
+      if (!favoriteGate.available) return;
+      favorite.mutate({ id, favorited: isFavorited !== true });
+    },
+    favoriteInFlight: favorite.isPending,
+    refetch: () => {
+      void detail.refetch();
+      void probe.refetch();
+    },
+  };
+}
+
+/** Renderless: the bag, handed to a render prop. Bring your own visuals, or
+ * import `<ListingDetailPane>` from `./default`. */
+export function ListingDetail(props: {
+  id: number;
+  viewerId?: string;
+  children: (bag: ListingDetailBag) => ReactNode;
+}): ReactElement {
+  const bag = useListingDetail(
+    props.id,
+    props.viewerId !== undefined ? { viewerId: props.viewerId } : {}
+  );
+  return <>{props.children(bag)}</>;
+}

package/src/headless/ListingsProvider.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { ModuleProvider } from "../model/context.js";
+import type { ListingsRuntime } from "../model/runtime.js";
+
+/**
+ * Renderless provider — puts one wired {@link ListingsRuntime} in context for
+ * every hook and headless component in the pair. Bring your own visual shell.
+ *
+ * ```tsx
+ * <ListingsProvider runtime={createListingsRuntime({ baseUrl: "/listings/api/v1/" })}>
+ *   <YourShopWindow />
+ * </ListingsProvider>
+ * ```
+ */
+export function ListingsProvider(props: {
+  runtime: ListingsRuntime;
+  children: ReactNode;
+}): ReactElement {
+  return <ModuleProvider runtime={props.runtime}>{props.children}</ModuleProvider>;
+}

package/src/headless/MyListings.tsx

@@ -0,0 +1,148 @@
+import { useMemo, useState } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  actionAvailable,
+  actionBlocked,
+  loadFailed,
+  loadLoading,
+  loadReady,
+  useActiveSessionReady,
+} from "@stapel/core";
+import type { ActionAvailability, LoadState } from "@stapel/core";
+import type {
+  ListingCard,
+  ListingPageParams,
+  MyCounters,
+} from "../api/types.js";
+import { MY_LISTINGS_SOURCE_MISSING } from "../model/mineSource.js";
+import type { MyListingsSource } from "../model/mineSource.js";
+import { useMyCounters } from "../model/queries.js";
+import { listingsQueryKeys, pageKey } from "../model/queryKeys.js";
+import { MY_LISTINGS_TABS } from "../model/status.js";
+import type { MyListingsTab } from "../model/status.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { useMandateGate } from "./useMandateGate.js";
+
+/**
+ * The owner's dashboard — and the one screen in this pair whose rows the
+ * backend cannot supply.
+ *
+ * The counters are REAL and are shown. The rows come from an injected
+ * `MyListingsSource`, and when there is none `rows` lands in the `failed` arm
+ * carrying a NAMED reason rather than as an empty list. `model/mineSource.ts`
+ * holds the whole argument and the upstream asks; this file is the bag over
+ * it.
+ */
+
+export interface MyListingsBag {
+  readonly tab: MyListingsTab;
+  readonly tabs: readonly MyListingsTab[];
+  setTab(tab: MyListingsTab): void;
+  /** The three real counts. */
+  readonly counters: LoadState<MyCounters>;
+  /** The rows for the current tab. `failed` with a named reason when no
+   * source is wired — never an empty list. */
+  readonly rows: LoadState<readonly ListingCard[]>;
+  readonly page: ListingPageParams;
+  readonly nextPage: ActionAvailability;
+  readonly prevPage: ActionAvailability;
+  goNext(): void;
+  goPrev(): void;
+  /** Whether the person may see this screen at all. */
+  readonly gate: ActionAvailability;
+  refetch(): void;
+}
+
+export interface UseMyListingsOptions {
+  readonly source?: MyListingsSource;
+  readonly initialTab?: MyListingsTab;
+  readonly limit?: number;
+}
+
+export function useMyListings(
+  options: UseMyListingsOptions = {}
+): MyListingsBag {
+  const gate = useMandateGate();
+  const sessionReady = useActiveSessionReady();
+  const [tab, setTabState] = useState<MyListingsTab>(
+    options.initialTab ?? "active"
+  );
+  const [page, setPage] = useState<ListingPageParams>(
+    options.limit !== undefined ? { limit: options.limit } : {}
+  );
+
+  const counters = useMyCounters();
+  const { source } = options;
+
+  const rowsQuery = useQuery({
+    queryKey: listingsQueryKeys.mine(tab, pageKey(page)),
+    queryFn: ({ signal }) =>
+      (source as MyListingsSource)({ tab, page, signal }),
+    enabled: source !== undefined && sessionReady && gate.available,
+    retry: false,
+  });
+
+  const rows: LoadState<readonly ListingCard[]> = useMemo(() => {
+    if (source === undefined) return loadFailed(MY_LISTINGS_SOURCE_MISSING);
+    if (rowsQuery.status === "error") return loadFailed(rowsQuery.error);
+    if (rowsQuery.data !== undefined) return loadReady(rowsQuery.data.items);
+    return loadLoading();
+  }, [source, rowsQuery.status, rowsQuery.error, rowsQuery.data]);
+
+  const envelope = rowsQuery.data;
+
+  return {
+    tab,
+    tabs: MY_LISTINGS_TABS,
+    setTab: (next) => {
+      // A cursor belongs to ONE ordered candidate set. Carried across a tab
+      // change it either bounces or honestly returns page four of a
+      // different list — the same property `@stapel/search-react` writes
+      // down for its own keyset state.
+      setPage(options.limit !== undefined ? { limit: options.limit } : {});
+      setTabState(next);
+    },
+    counters:
+      counters.status === "error"
+        ? loadFailed(counters.error)
+        : counters.data !== undefined
+          ? loadReady(counters.data)
+          : loadLoading(),
+    rows,
+    page,
+    nextPage:
+      envelope?.has_next === true && envelope.next_anchor != null
+        ? actionAvailable()
+        : actionBlocked(LISTINGS_I18N_KEYS.pageNext),
+    prevPage:
+      envelope?.has_prev === true && envelope.prev_anchor != null
+        ? actionAvailable()
+        : actionBlocked(LISTINGS_I18N_KEYS.pagePrev),
+    goNext: () => {
+      const anchor = envelope?.next_anchor;
+      if (anchor == null) return;
+      setPage((current) => ({ ...current, anchor, direction: "next" }));
+    },
+    goPrev: () => {
+      const anchor = envelope?.prev_anchor;
+      if (anchor == null) return;
+      setPage((current) => ({ ...current, anchor, direction: "prev" }));
+    },
+    gate,
+    refetch: () => {
+      void counters.refetch();
+      void rowsQuery.refetch();
+    },
+  };
+}
+
+/** Renderless: the bag, handed to a render prop. */
+export function MyListings(
+  props: UseMyListingsOptions & {
+    children: (bag: MyListingsBag) => ReactNode;
+  }
+): ReactElement {
+  const bag = useMyListings(props);
+  return <>{props.children(bag)}</>;
+}

package/src/headless/useMandateGate.ts

@@ -0,0 +1,40 @@
+import { matchMandate, useMandate } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import { actionAvailable, actionBlocked } from "@stapel/core";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+
+/**
+ * "May this person act at all?" — the first gate on every write in the pair.
+ *
+ * Posting a listing, saving a draft, marking something sold and saving a
+ * favourite are all `IsAuthenticated`. A visitor meeting one of them must be
+ * told to sign in, WITH the reason and with a way to do it: a hidden button
+ * teaches nothing (private-space canon §6.3), and a 401 after the click
+ * teaches it too late.
+ *
+ * The axis is read through core's `MandateSource` seam, never derived here. A
+ * storefront's derivation is "is there a session?"; a tenant app's is
+ * `@stapel/workspaces-react`'s. This pair asks and does not care which.
+ * `matchMandate` has five required arms, so the two `unresolved` outcomes
+ * cannot fall into the refusal's branch by omission:
+ *
+ *  - `asking`  — we have not finished asking. The control waits; it does not
+ *                say "you may not".
+ *  - `unavailable` — we COULD NOT ask. Also not "you may not": the storefront
+ *                spec's own negative leg (§7.4) is that `/me` answering 503
+ *                must not render as a refusal.
+ *
+ * Outside a `<MandateProvider>` core answers `unresolved/unavailable` rather
+ * 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 {
+  const mandate = useMandate();
+  return matchMandate<ActionAvailability>(mandate, {
+    member: () => actionAvailable(),
+    guest: () => actionBlocked(LISTINGS_I18N_KEYS.blockedGuest),
+    anonymous: () => actionBlocked(LISTINGS_I18N_KEYS.blockedSignIn),
+    asking: () => actionBlocked(LISTINGS_I18N_KEYS.blockedMandateUnknown),
+    unavailable: () => actionBlocked(LISTINGS_I18N_KEYS.blockedMandateUnknown),
+  });
+}

package/src/i18n/errorsMap.ts

@@ -0,0 +1,62 @@
+/**
+ * The pair's error map (frontend-standard §4 checklist #7, frontend-core
+ * §2.5): the generated `code → { status, params, remediation, en }` catalog
+ * plus a tiny `explain()` lookup. Backs the manifest `errors` block and gives
+ * hosts a mechanical UX branch beside `t(code, params)`. The map itself is
+ * generated from the backend registry (`pnpm gen:errors`); this file only
+ * adds the lookup helper, names the three refusals a storefront actually
+ * meets, and re-exports the public surface.
+ */
+import { LISTINGS_ERRORS } from "./generated/errors.gen.js";
+import type { Remediation } from "./generated/errors.gen.js";
+
+export {
+  LISTINGS_ERRORS,
+  LISTINGS_ERROR_CODES,
+  listingsErrorBundleEn,
+} from "./generated/errors.gen.js";
+export type {
+  ListingsErrorCode,
+  ListingsErrorSpec,
+  Remediation,
+} from "./generated/errors.gen.js";
+
+/**
+ * The lifecycle refusal, and the one code in this registry that carries the
+ * information needed to explain itself: `params.from_status` is the state the
+ * server refused to move OUT of (`views._transition`). A skin renders
+ * "a listing that is sold cannot be archived that way", not "conflict".
+ */
+export const LISTING_INVALID_TRANSITION = "error.409.invalid_listing_transition";
+
+/** Deleting something that is on sale. The remedy is in the sentence:
+ * archive it first. */
+export const LISTING_CANNOT_DELETE_ACTIVE =
+  "error.409.listing_cannot_delete_active";
+
+/**
+ * The publish refusal that is NOT a per-field verdict.
+ *
+ * `publish` answers an invalid draft with a bare `ValidationBatchResult`; this
+ * code is what it answers when the PROMOTION fails afterwards — today that
+ * means `REQUIRE_IMAGE_ON_PUBLISH` with an empty gallery. Two 400s, two
+ * meanings; `model/validation.ts`'s `publishRefusal` is the one place that
+ * tells them apart.
+ */
+export const LISTING_PUBLISH_VALIDATION_FAILED =
+  "error.400.publish_validation_failed";
+
+/** Somebody else's listing. Every owner operation routes through
+ * `views._get_own` — except `PUT`/`PATCH`, which is why this pair does not
+ * call them (`api/listingsApi.ts`). */
+export const LISTING_NOT_OWNER = "error.403.listing_not_owner";
+
+/**
+ * Resolve a backend error code to its remediation hint, or `undefined` for a
+ * code this module doesn't know (e.g. a cross-cutting `stapel.http.*`
+ * fallback). Zero guessing at runtime — a static lookup over the generated map.
+ */
+export function explainListingsError(code: string): Remediation | undefined {
+  return (LISTINGS_ERRORS as Record<string, { remediation: Remediation }>)[code]
+    ?.remediation;
+}