@stapel/listings-react 0.4.0 → 0.8.0

package/src/api/generated/schema.ts

@@ -12,12 +12,21 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
         get: operations["listings_api_v1_listings_list"];
         put?: never;
         /**
-         * @description Listings CRUD plus owner lifecycle actions and favorites.
+         * @description Open a draft — the first act of becoming a seller, so the guest
+         *     wall stands here and not only at ``publish``.
          *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
@@ -38,6 +47,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
         get: operations["listings_api_v1_listings_retrieve"];
@@ -53,6 +70,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
         delete: operations["listings_api_v1_listings_destroy"];
@@ -61,6 +86,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
         patch: operations["listings_api_v1_listings_partial_update"];
@@ -78,6 +111,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         post: operations["listings_api_v1_listings_archive_create"];
@@ -120,6 +161,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         post: operations["listings_api_v1_listings_favorite_create"];
@@ -139,7 +188,8 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * @description Listings CRUD plus owner lifecycle actions and favorites.
+         * @description Put a listing in front of buyers — the act the wall is named for:
+         *     a seller nobody can reach again is not a seller.
          *
          *     **Permissions:** `IsAuthenticated`
          */
@@ -181,6 +231,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `AllowAny`
          */
         get: operations["listings_api_v1_listings_status_retrieve"];
@@ -204,6 +262,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         post: operations["listings_api_v1_listings_unfavorite_create"];
@@ -223,6 +289,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         get: operations["listings_api_v1_listings_validate_draft_retrieve"];
@@ -244,6 +318,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         get: operations["listings_api_v1_listings_my_counters_retrieve"];
@@ -265,6 +347,14 @@ export interface paths {
         /**
          * @description Listings CRUD plus owner lifecycle actions and favorites.
          *
+         *     Read and write live in one class, so the guest wall
+         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
+         *     is applied per ACTION and never as a class permission: an anonymous
+         *     session must keep browsing and keep its favorites, and only the
+         *     authorship actions — ``create``, ``update``/``partial_update``,
+         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
+         *     seller.
+         *
          *     **Permissions:** `IsAuthenticated`
          */
         get: operations["listings_api_v1_listings_my_favorites_list"];
@@ -664,7 +754,7 @@ export interface components {
             images_draft?: string[];
             location_id_draft?: string;
             location_label_draft?: string;
-            geohash_draft?: string;
+            readonly geohash_draft: string;
             /** Format: decimal */
             lat_draft?: string | null;
             /** Format: decimal */
@@ -805,7 +895,7 @@ export interface components {
             images_draft?: string[];
             location_id_draft?: string;
             location_label_draft?: string;
-            geohash_draft?: string;
+            readonly geohash_draft?: string;
             /** Format: decimal */
             lat_draft?: string | null;
             /** Format: decimal */

package/src/default/FavoritesPane.tsx

@@ -6,19 +6,53 @@
  * "You have not saved anything yet" and "we could not load your favourites"
  * are the pair a `data ?? []` would have merged, and merging them is exactly
  * the substitution that cost the fleet an incident (spec §7.4).
+ *
+ * ── A visitor is told ONE thing ────────────────────────────────────────────
+ *
+ * `useFavorites` disables the query without a mandate, so a visitor's `rows`
+ * sit in `loading` forever — and the pane rendered the blocked notice AND the
+ * spinner underneath it, saying "you cannot see this" and "we are fetching it"
+ * at the same time, with no sign-in link anywhere on the screen. The gate is
+ * now the WHOLE body: one designed state, with the door the container supplies
+ * (`signIn`) inside it, and nothing else drawn.
+ *
+ * The pager obeys the same rule. `Previous`/`Next` were rendered disabled in
+ * every state including empty, failed and blocked — two controls that meant
+ * nothing, three times over. They render when there is a page to go to.
+ *
+ * And each one renders only when ITS page exists. The keyset gates name the
+ * missing page with the button's own label key, so a blocked `Previous` drew
+ * the word twice — once as a dead button, once as its own "reason". A pager
+ * does not explain itself: the page indicator says where you are, and a
+ * direction with nowhere to go is simply not drawn.
  */
-import type { ReactElement } from "react";
-import { Alert, Button, Empty, Flex, Space, Spin, Typography } from "antd";
-import { matchList, useDescribeFlowError, useT } from "@stapel/core";
-import type { LinkComponent } from "@stapel/core";
+import type { ReactElement, ReactNode } from "react";
+import { Button, Flex, Typography } from "antd";
+import {
+  EmptyState,
+  ErrorAlert,
+  SkinTheme,
+} from "@stapel/tokens-antd/skin";
+import { matchList, useT } from "@stapel/core";
+import type { LinkComponent, SignInCtaProp } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
 import { useFavorites } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import { ErrorAlert } from "./ErrorAlert.js";
 import { ListingCard } from "./ListingCard.js";
 import type { ListingCardOpenProps } from "./ListingCard.js";
-import { ListingsSkinTheme } from "./theme.js";
+import { SignInLink } from "./SignInLink.js";
 import type { ThemeModeProp } from "./types.js";
 
+/** The narrowest a card may get before the grid drops a column — the same
+ * element-relative rule the detail gallery uses. It was `width: 240`, which
+ * left two cards floating in a 2560px pane and overflowed a 390px one. */
+export const FAVORITES_CARD_MIN = "15rem";
+
+/** How wide the saved grid may get before it stops being a grid and becomes
+ * three cards adrift in a 1280px window. A measure, not a breakpoint: the
+ * cards keep filling it, and past it the page centres. */
+export const FAVORITES_MEASURE = "72rem";
+
 /** How a card in this grid opens — the same one-contract union `<ListingCard>`
  * takes, one level up, so a pane cannot re-introduce the double navigation the
  * card no longer allows. */
@@ -41,7 +75,21 @@ export type FavoritesPaneOpenProps =
       readonly linkComponent?: undefined;
     };
 
-export type FavoritesPaneProps = ThemeModeProp & FavoritesPaneOpenProps;
+/** The way OUT of an empty favourites list. */
+export interface FavoritesBrowseCtaProp {
+  /**
+   * What a person with nothing saved can do next — a "Browse listings"
+   * button, supplied by the container because only it knows where the
+   * catalogue lives. An empty state without one is a dead end, and this
+   * screen was one of four sharing a single stock illustration and no exit.
+   */
+  readonly browseCta?: ReactNode;
+}
+
+export type FavoritesPaneProps = ThemeModeProp &
+  SignInCtaProp &
+  FavoritesBrowseCtaProp &
+  FavoritesPaneOpenProps;
 
 /** The card's own open props for one row. One arm, never two. */
 function cardOpenProps(
@@ -60,93 +108,119 @@ function cardOpenProps(
 
 export function FavoritesPane(props: FavoritesPaneProps): ReactElement {
   const t = useT();
-  const describe = useDescribeFlowError();
   const bag = useFavorites();
+  const paged = bag.prevPage.available || bag.nextPage.available;
 
   return (
-    <ListingsSkinTheme {...(props.mode !== undefined ? { mode: props.mode } : {})}>
-      <Flex vertical gap={16} data-testid="listings-favorites">
+    <SkinTheme
+      surface="base"
+      style={{ padding: spacing[4], maxWidth: FAVORITES_MEASURE }}
+      {...(props.mode !== undefined ? { mode: props.mode } : {})}
+    >
+      <Flex vertical gap={spacing[4]} data-testid="listings-favorites">
         <Typography.Title level={3}>
           {t(LISTINGS_I18N_KEYS.favoritesTitle)}
         </Typography.Title>
 
         {!bag.gate.available ? (
-          <Alert
-            type="info"
-            showIcon
-            data-testid="listings-favorites-blocked"
-            message={t(bag.gate.block.code, bag.gate.block.params)}
+          // The whole body, not a banner over a spinner. A blocked screen has
+          // one state and it carries its own way out.
+          <EmptyState
+            testId="listings-favorites-blocked"
+            title={t(bag.gate.block.code, bag.gate.block.params)}
+            hint={t(LISTINGS_I18N_KEYS.favoritesSignInHint)}
+            action={
+              <SignInLink cta={props.signIn} testId="listings-favorites-sign-in" />
+            }
           />
-        ) : null}
-
-        {matchList(bag.rows, {
-          loading: () => (
-            <Flex justify="center" data-testid="listings-favorites-loading">
-              <Spin aria-label={t(LISTINGS_I18N_KEYS.favoritesLoading)} />
-            </Flex>
-          ),
-          failed: () => (
-            <ErrorAlert
-              testId="listings-favorites-error"
-              error={describe({
-                code: LISTINGS_I18N_KEYS.favoritesLoadFailed,
-                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}
+        ) : (
+          <>
+            {matchList(bag.rows, {
+              loading: () => (
+                <div
+                  role="status"
+                  aria-busy="true"
+                  aria-label={t(LISTINGS_I18N_KEYS.favoritesLoading)}
+                  data-testid="listings-favorites-loading"
+                  data-stapel-load-state="loading"
+                />
+              ),
+              failed: (error) => (
+                <ErrorAlert
+                  testId="listings-favorites-error"
+                  thrown={error}
+                  message={t(LISTINGS_I18N_KEYS.favoritesLoadFailed)}
+                  onRetry={bag.refetch}
+                  retryLabel={t(LISTINGS_I18N_KEYS.mineRetry)}
+                />
+              ),
+              empty: () => (
+                <EmptyState
+                  testId="listings-favorites-empty"
+                  title={t(LISTINGS_I18N_KEYS.favoritesEmpty)}
+                  hint={t(LISTINGS_I18N_KEYS.favoritesEmptyHint)}
+                  {...(props.browseCta !== undefined
+                    ? { action: props.browseCta }
+                    : {})}
+                />
+              ),
+              ready: (rows) => (
+                <div
+                  data-testid="listings-favorites-grid"
+                  style={{
+                    display: "grid",
+                    gridTemplateColumns: `repeat(auto-fill, minmax(${FAVORITES_CARD_MIN}, 1fr))`,
+                    gap: spacing[4],
+                  }}
                 >
-                  {t(LISTINGS_I18N_KEYS.mineRetry)}
-                </Button>
-              }
-            />
-          ),
-          empty: () => (
-            <Empty
-              data-testid="listings-favorites-empty"
-              description={t(LISTINGS_I18N_KEYS.favoritesEmpty)}
-            />
-          ),
-          ready: (rows) => (
-            <Flex wrap gap={16} data-testid="listings-favorites-grid">
-              {rows.map((row) => (
-                <div key={row.id} style={{ width: 240 }}>
-                  <ListingCard listing={row} {...cardOpenProps(props, row.id)} />
+                  {rows.map((row) => (
+                    <ListingCard
+                      key={row.id}
+                      listing={row}
+                      blockedReason="line"
+                      {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
+                      {...cardOpenProps(props, row.id)}
+                    />
+                  ))}
                 </div>
-              ))}
-            </Flex>
-          ),
-        })}
+              ),
+            })}
 
-        <Space>
-          <Button
-            size="small"
-            disabled={!bag.prevPage.available}
-            data-testid="listings-favorites-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-favorites-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>
+            {paged ? (
+              <Flex gap={spacing[3]} wrap align="center">
+                {bag.prevPage.available ? (
+                  <Button
+                    size="small"
+                    data-testid="listings-favorites-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>
+                ) : null}
+                <Typography.Text
+                  type="secondary"
+                  data-testid="listings-favorites-page"
+                >
+                  {t(LISTINGS_I18N_KEYS.pageIndicator, { page: bag.pageNumber })}
+                </Typography.Text>
+                {bag.nextPage.available ? (
+                  <Button
+                    size="small"
+                    data-testid="listings-favorites-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>
+                ) : null}
+              </Flex>
+            ) : null}
+          </>
+        )}
       </Flex>
-    </ListingsSkinTheme>
+    </SkinTheme>
   );
 }