@stapel/listings-react 0.1.0

package/src/default/StatusTags.tsx

@@ -0,0 +1,86 @@
+/**
+ * The two axes, drawn as two.
+ *
+ * `<LifecycleTag>` is the state; `<ModerationNote>` is what the moderation
+ * axis adds ON TOP of it, and it renders nothing when there is nothing to add
+ * (an approved listing owes its owner no note). Keeping them separate is what
+ * makes "Published" and "changes under review" appear side by side rather
+ * than one overwriting the other — the failure `model/status.ts` exists to
+ * prevent, made visual.
+ *
+ * A tone maps to an antd preset here and nowhere else. No hex leaves this
+ * file, because none enters it: the presets resolve through the theme, which
+ * resolves through `@stapel/tokens`.
+ */
+import type { ReactElement } from "react";
+import { Alert, Tag } from "antd";
+import { useT } from "@stapel/core";
+import type { ListingStatusTone, ListingStatusView } from "../model/status.js";
+
+const TONE_COLOR: Readonly<Record<ListingStatusTone, string>> = {
+  neutral: "default",
+  waiting: "processing",
+  good: "success",
+  warning: "warning",
+  stopped: "error",
+};
+
+const TONE_ALERT: Readonly<
+  Record<ListingStatusTone, "info" | "success" | "warning" | "error">
+> = {
+  neutral: "info",
+  waiting: "info",
+  good: "success",
+  warning: "warning",
+  stopped: "error",
+};
+
+export interface ListingStatusProps {
+  readonly status: ListingStatusView;
+}
+
+/** The lifecycle state — the field that decides whether anyone else can see
+ * this listing. */
+export function LifecycleTag(props: ListingStatusProps): ReactElement {
+  const t = useT();
+  return (
+    <Tag
+      color={TONE_COLOR[props.status.lifecycle.tone]}
+      data-testid="listings-status-tag"
+      data-listing-status={props.status.lifecycle.status}
+    >
+      {t(props.status.lifecycle.labelKey)}
+    </Tag>
+  );
+}
+
+/**
+ * What the moderation axis adds. Renders `null` when it adds nothing, so a
+ * calm listing shows no banner at all.
+ */
+export function ModerationNote(props: ListingStatusProps): ReactElement | null {
+  const t = useT();
+  const notice = props.status.moderation;
+  if (notice === undefined) return null;
+  return (
+    <Alert
+      type={TONE_ALERT[notice.tone]}
+      showIcon
+      data-testid="listings-moderation-note"
+      data-listing-moderation={notice.moderationStatus}
+      data-listing-live-under-review={String(notice.liveDuringReview)}
+      message={t(notice.messageKey)}
+    />
+  );
+}
+
+/** Both, in the order a person reads them: what it IS, then what is happening
+ * to it. */
+export function ListingStatusBlock(props: ListingStatusProps): ReactElement {
+  return (
+    <>
+      <LifecycleTag status={props.status} />
+      <ModerationNote status={props.status} />
+    </>
+  );
+}

package/src/default/icons.tsx

@@ -0,0 +1,31 @@
+/**
+ * One inline glyph: the favourite heart, filled and outlined.
+ *
+ * No `@ant-design/icons` dependency — the house convention (profiles-react's
+ * `icons.tsx`, shell-react's icon registry): a plain monochrome
+ * `currentColor` SVG, so it inherits the theme instead of carrying a colour
+ * of its own, and the pair stays one package lighter.
+ *
+ * `aria-hidden` on both: the button that holds them carries the label, and a
+ * glyph announced beside its own label reads the action twice.
+ */
+import type { ReactElement } from "react";
+
+export function HeartIcon(props: { filled: boolean }): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill={props.filled ? "currentColor" : "none"}
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-hidden="true"
+    >
+      <path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8z" />
+    </svg>
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,35 @@
+/**
+ * `@stapel/listings-react/default` — the antd skin: the card another pair
+ * renders, the listing page, the composer and the seller's dashboard.
+ *
+ * A separate entry point (the convention every pair's `/default` follows) so
+ * a host rendering its own visuals over the bags never pulls `antd` into its
+ * bundle.
+ *
+ * ```tsx
+ * import { ListingsProvider, createListingsRuntime } from "@stapel/listings-react";
+ * import { ListingCard, ListingDetailPane } from "@stapel/listings-react/default";
+ *
+ * // the search pair's card slot — the container is the seam, not an import
+ * <SearchPage renderCard={(item) => <ListingCard listing={item.card} href={`/l/${item.id}`} />} />
+ * ```
+ */
+export { ListingCard } from "./ListingCard.js";
+export type { ListingCardProps } from "./ListingCard.js";
+export { ListingDetailPane } from "./ListingDetailPane.js";
+export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
+export { ListingComposerPage } from "./ListingComposerPage.js";
+export type { ListingComposerPageProps } from "./ListingComposerPage.js";
+export { MyListingsPane } from "./MyListingsPane.js";
+export type { MyListingsPaneProps } from "./MyListingsPane.js";
+export { FavoritesPane } from "./FavoritesPane.js";
+export type { FavoritesPaneProps } from "./FavoritesPane.js";
+
+export { LifecycleTag, ListingStatusBlock, ModerationNote } from "./StatusTags.js";
+export type { ListingStatusProps } from "./StatusTags.js";
+export { ListingPhoto } from "./ListingPhoto.js";
+export type { ListingPhotoProps } from "./ListingPhoto.js";
+export { ErrorAlert } from "./ErrorAlert.js";
+export { ListingsSkinTheme } from "./theme.js";
+export type { ListingsSkinThemeProps } from "./theme.js";
+export type { ThemeModeProp } from "./types.js";

package/src/default/theme.tsx

@@ -0,0 +1,67 @@
+/**
+ * The default skin's INTERNAL theme provider — every `/default` surface wraps
+ * itself in this, so the skin is readable no matter what the host supplies
+ * (tracker #26: a skin set with no internal provider once inherited a theme
+ * bridge serving light-mode values inside a dark document — text on
+ * background at 1.00:1). The theme derives from `@stapel/tokens` via
+ * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
+ * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
+ * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
+ *
+ * This is also what "override styles" means for this pair: a storefront
+ * retheming through the §68 token JSON regenerates its `--stapel-*` custom
+ * properties and the result page follows with zero code — a far better deal
+ * than a prop-per-colour API, and the reason the skin has none.
+ */
+import { useMemo } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { ConfigProvider } from "antd";
+import {
+  resolveThemeMode,
+  toAntdTheme,
+  toAntdThemeConfig,
+} from "@stapel/tokens-antd";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+export interface ListingsSkinThemeProps {
+  /**
+   * Light or dark. Defaults to the mode the host's document declares
+   * (`resolveThemeMode()`). Pass explicitly to pin a side.
+   */
+  readonly mode?: ThemeMode;
+  /** Extra styles merged onto the themed root element (layout only — colors
+   * come from the mode). */
+  readonly style?: CSSProperties;
+  readonly children: ReactNode;
+}
+
+/**
+ * `<ListingsSkinTheme/>` — the self-theming wrapper of
+ * `@stapel/listings-react/default`. Standalone use is supported (wrap any
+ * composition of the skin's parts once); the shipped surfaces
+ * (`ListingCard`, `ListingDetailPane`, `ListingComposerPage`,
+ * `MyListingsPane`, `FavoritesPane`)
+ * each already wrap themselves, and nested antd
+ * `ConfigProvider`s merge, so composing them under one `ListingsSkinTheme`
+ * stays correct.
+ */
+export function ListingsSkinTheme(props: ListingsSkinThemeProps): ReactElement {
+  const mode = props.mode ?? resolveThemeMode();
+  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
+  const token = useMemo(() => toAntdTheme(mode), [mode]);
+  return (
+    <ConfigProvider theme={theme}>
+      <div
+        data-listings-skin-root
+        data-listings-skin-mode={mode}
+        style={{
+          color: token.colorText,
+          backgroundColor: token.colorBgContainer,
+          ...props.style,
+        }}
+      >
+        {props.children}
+      </div>
+    </ConfigProvider>
+  );
+}

package/src/default/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Small shared types for the `/default` skin — kept in one place so every
+ * surface takes the same `mode` prop and re-exports the same error dialect.
+ */
+export type { FlowError } from "@stapel/core";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+/** 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;
+}

package/src/flows/registry.ts

@@ -0,0 +1,45 @@
+/**
+ * Zero-flow registry shim. stapel-listings annotates no `@flow_step`: its
+ * `docs/flows.json` is an empty array, so `gen:flows` skips emission for this
+ * pair (no `flows/generated/`). This hand-written shim preserves the pair's
+ * public flow-registry surface at its zero-flow shape — the stapel-chat /
+ * stapel-cdn / stapel-categories precedent, three directories over.
+ *
+ * Submitting a listing IS multi-step, and it is worth saying why that does
+ * not contradict the empty artifact. The steps —
+ *
+ *     create draft → save draft (repeatedly) → validate → publish
+ *
+ * — are four independent endpoint calls that the server does not sequence:
+ * nothing on the backend remembers that a `save-draft` was part of a
+ * submission, `publish` may be called on a draft created a week ago, and
+ * `validate-draft` is optional. A `@flow_step`-annotated funnel would be a
+ * frontend fiction in a machine-readable artifact. The pair's real state
+ * machine lives in `headless/ListingComposer.tsx`, and its stages are named
+ * there ({@link ComposeStage}) so analytics can still follow the funnel.
+ *
+ * When the backend annotates flows, `pnpm gen:flows` emits
+ * `./generated/flows.gen.ts` again — replace these exports with re-exports
+ * from it (the shapes match by construction) and delete this file.
+ */
+export const LISTINGS_FLOWS = {} as const;
+
+/** Canonical flow ids present in flows.json (none yet — see above). */
+export type ListingsFlowId = keyof typeof LISTINGS_FLOWS;
+
+export type ListingsFlowSpec = (typeof LISTINGS_FLOWS)[ListingsFlowId];
+
+export interface FlowEndpoint {
+  readonly method: string;
+  readonly path: string;
+}
+
+/** All HTTP endpoints a flow touches, in step order (for the contract test). */
+export function flowEndpoints(id: ListingsFlowId): readonly FlowEndpoint[] {
+  // Same widened body as the generated registry's — valid for the zero-flow
+  // shape AND correct once flows exist.
+  const spec = LISTINGS_FLOWS[id] as
+    | { readonly steps: readonly { readonly endpoints: readonly FlowEndpoint[] }[] }
+    | undefined;
+  return spec ? spec.steps.flatMap((step) => step.endpoints) : [];
+}

package/src/headless/Favorites.tsx

@@ -0,0 +1,137 @@
+import { useState } from "react";
+import type { ReactElement, ReactNode } from "react";
+import {
+  actionAvailable,
+  actionBlocked,
+  firstBlock,
+  loadFailed,
+  loadLoading,
+  loadReady,
+} from "@stapel/core";
+import type { ActionAvailability, LoadState } from "@stapel/core";
+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";
+
+/**
+ * Saving something for later — first-class in stapel-listings (a `Favorite`
+ * model, three endpoints) and therefore first-class here (owner verdict F7).
+ *
+ * Two surfaces over one contract: {@link useFavoriteToggle} is the heart on a
+ * card, {@link useFavorites} is the page listing what was saved.
+ */
+
+export interface FavoriteToggleBag {
+  readonly favorited: boolean;
+  /** Blocked with the reason for a visitor, a guest, an unknown mandate, or
+   * while the previous toggle is still in flight. Never a hidden heart: a
+   * control that disappears for a visitor teaches them nothing, and the CTA
+   * to sign in is the whole point of showing it (spec §6.2 item 6). */
+  readonly gate: ActionAvailability;
+  toggle(): void;
+  readonly inFlight: boolean;
+  readonly error: unknown;
+}
+
+/**
+ * The heart on one card.
+ *
+ * `favorited` is the caller's — `ListingCard.is_favorited` comes down with
+ * every card, so a grid needs no extra read. It is `null` for an anonymous
+ * reader (`with_favorited` annotates `Value(None)`), which is a THIRD state
+ * and not `false`: "we did not ask" versus "not saved". The gate is what
+ * renders it, so the distinction never has to be squeezed into the boolean.
+ */
+export function useFavoriteToggle(
+  id: number,
+  favorited: boolean | null | undefined
+): FavoriteToggleBag {
+  const mandate = useMandateGate();
+  const mutation = useFavoriteListing();
+  const gate = firstBlock(
+    mandate,
+    mutation.isPending
+      ? actionBlocked(LISTINGS_I18N_KEYS.blockedInFlight)
+      : actionAvailable()
+  );
+  return {
+    favorited: favorited === true,
+    gate,
+    toggle: () => {
+      if (!gate.available) return;
+      mutation.mutate({ id, favorited: favorited !== true });
+    },
+    inFlight: mutation.isPending,
+    error: mutation.error,
+  };
+}
+
+export interface FavoritesBag {
+  readonly rows: LoadState<readonly ListingCard[]>;
+  readonly page: ListingPageParams;
+  readonly nextPage: ActionAvailability;
+  readonly prevPage: ActionAvailability;
+  goNext(): void;
+  goPrev(): void;
+  readonly gate: ActionAvailability;
+  refetch(): void;
+}
+
+export interface UseFavoritesOptions {
+  readonly limit?: number;
+}
+
+/** 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();
+  const [page, setPage] = useState<ListingPageParams>(
+    options.limit !== undefined ? { limit: options.limit } : {}
+  );
+  const query = useMyFavorites(page, { enabled: gate.available });
+  const envelope = query.data;
+
+  return {
+    rows:
+      query.status === "error"
+        ? loadFailed(query.error)
+        : envelope !== undefined
+          ? loadReady(envelope.items)
+          : loadLoading(),
+    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 query.refetch();
+    },
+  };
+}
+
+/** Renderless: the bag, handed to a render prop. */
+export function Favorites(
+  props: UseFavoritesOptions & {
+    children: (bag: FavoritesBag) => ReactNode;
+  }
+): ReactElement {
+  const bag = useFavorites(props);
+  return <>{props.children(bag)}</>;
+}

package/src/headless/ListingActions.tsx

@@ -0,0 +1,101 @@
+import {
+  actionAvailable,
+  actionBlocked,
+  firstBlock,
+} from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import type { ListingLifecycleStatus } from "../api/types.js";
+import {
+  useArchiveListing,
+  useCompleteListing,
+  useDeleteListing,
+} from "../model/mutations.js";
+import { canDelete, canTransition } from "../model/transitions.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import { useMandateGate } from "./useMandateGate.js";
+
+/**
+ * The three lifecycle moves an owner can actually request, each behind a gate
+ * that states its reason.
+ *
+ * ── The mirror is UX, the 409 is the verdict ───────────────────────────────
+ *
+ * `LISTING_TRANSITIONS` (`model/transitions.ts`) is a copy of the server's
+ * whitelist, and it exists so a control can be switched off WITH a sentence:
+ * "a listing that is sold cannot be archived that way" beats a toast after
+ * the click. The server still decides — `transition_to` raises and the view
+ * answers 409 `error.409.invalid_listing_transition` with
+ * `params.from_status` — and that refusal is rendered as the named thing it
+ * is. The mirror may never block what the server would allow, which is why it
+ * is a copy of the table and not a summary of it.
+ */
+export interface ListingActionsBag {
+  readonly archive: ActionAvailability;
+  readonly complete: ActionAvailability;
+  readonly remove: ActionAvailability;
+  doArchive(): void;
+  doComplete(): void;
+  doRemove(): void;
+  readonly inFlight: boolean;
+  /** The last refusal from any of the three, in the one error dialect. */
+  readonly error: unknown;
+}
+
+export function useListingActions(
+  id: number,
+  status: ListingLifecycleStatus | undefined
+): ListingActionsBag {
+  const mandate = useMandateGate();
+  const archive = useArchiveListing();
+  const complete = useCompleteListing();
+  const remove = useDeleteListing();
+
+  const inFlight = archive.isPending || complete.isPending || remove.isPending;
+  const busy: ActionAvailability = inFlight
+    ? actionBlocked(LISTINGS_I18N_KEYS.blockedInFlight)
+    : actionAvailable();
+
+  // An unknown status blocks with the loading reason rather than guessing:
+  // the whitelist cannot be consulted for a state nobody has read yet.
+  const known: ActionAvailability =
+    status === undefined
+      ? actionBlocked(LISTINGS_I18N_KEYS.detailLoading)
+      : actionAvailable();
+
+  function transitionGate(to: ListingLifecycleStatus): ActionAvailability {
+    if (status === undefined) return known;
+    return canTransition(status, to)
+      ? actionAvailable()
+      : actionBlocked(LISTINGS_I18N_KEYS.blockedTransition, {
+          from_status: status,
+        });
+  }
+
+  const archiveGate = firstBlock(mandate, known, busy, transitionGate("archived"));
+  const completeGate = firstBlock(mandate, known, busy, transitionGate("sold"));
+  const removeGate = firstBlock(
+    mandate,
+    known,
+    busy,
+    status !== undefined && !canDelete(status)
+      ? actionBlocked(LISTINGS_I18N_KEYS.blockedDeleteActive)
+      : actionAvailable()
+  );
+
+  return {
+    archive: archiveGate,
+    complete: completeGate,
+    remove: removeGate,
+    doArchive: () => {
+      if (archiveGate.available) archive.mutate(id);
+    },
+    doComplete: () => {
+      if (completeGate.available) complete.mutate(id);
+    },
+    doRemove: () => {
+      if (removeGate.available) remove.mutate(id);
+    },
+    inFlight,
+    error: archive.error ?? complete.error ?? remove.error,
+  };
+}