@stapel/listings-react 0.18.2 → 0.20.0

package/src/model/engagement.ts

@@ -0,0 +1,118 @@
+/**
+ * "Have I already seen this one?" — the engagement axis of a listing row, and
+ * the OVERLAY that is the only way a storefront ever gets an answer.
+ *
+ * A classified's results page is mostly re-reading: the same twenty offers
+ * scrolled past for the third evening in a row. Every mature one marks the
+ * rows you already opened, and a shopper who cannot see which those are is
+ * paying attention to the same card repeatedly. `viewed` is that mark and
+ * `view_count` is the seller-facing counterpart on the listing page.
+ *
+ * ── Why the row alone is not enough, and the overlay is the load-bearing half
+ *
+ * stapel-listings puts `viewed` / `view_count` on its own card and detail
+ * serializers, and on the listing PAGE that is the end of the story. But the
+ * two surfaces a buyer actually scrolls — the home feed and the SERP — are
+ * not served by this module at all: their cards come out of the SEARCH index,
+ * whose stored document can carry neither a flag that differs per reader nor
+ * a counter that moves faster than a re-index. So on exactly the screens the
+ * feature exists for, `viewed` and `is_favorited` never arrive on the row,
+ * every card renders undimmed with an outline heart, and nothing anywhere
+ * reports a problem.
+ *
+ * `GET /listings/engagement/?ids=…` is the answer the backend built for it:
+ * ONE call for a whole page, `{id: {view_count, viewed, is_favorited}}`,
+ * `AllowAny` so a signed-out grid is not a second code path. This module is
+ * the READING side of it — what a row means, how one entry is found in a
+ * batch, and how an entry is laid over a row a container fetched from
+ * somewhere else. The id normalizer both the request and its cache key are
+ * built from lives with the wire types (`engagementIds`), because the cap it
+ * enforces is the server's.
+ *
+ * ── The rule every function here keeps ────────────────────────────────────
+ *
+ * **Absent, `null` and `NaN` all mean "draw nothing extra".** No dimming, no
+ * number, no warning, no log line, and — for a failed overlay — no banner
+ * over a grid that is otherwise working. A pair that printed "0 views" for a
+ * field the server never sent would be inventing a fact about a seller's
+ * listing; a pair that turned a decoration's 500 into an error state would
+ * have taken a working results page away from a shopper over a flag. A grid
+ * that renders is worth more than a flag.
+ */
+import type {
+  ListingCard,
+  ListingEngagement,
+  ListingEngagementBatch,
+  ListingEngagementFields,
+} from "../api/types.js";
+
+/**
+ * Has this reader already opened this listing?
+ *
+ * `true` and only `true`. `null` is "we did not ask on this person's behalf"
+ * — the same third state `is_favorited` carries for an anonymous read — and a
+ * row nobody asked about is not a row somebody has seen.
+ */
+export function isListingViewed(
+  row: ListingEngagementFields | undefined
+): boolean {
+  return row?.viewed === true;
+}
+
+/**
+ * How many times the listing has been opened, or `undefined` where there is
+ * no number to show.
+ *
+ * `Number.isFinite` rather than `typeof === "number"`: a JSON `NaN` cannot
+ * arrive, but a count computed by a host from something absent can, and
+ * "NaN views" on a seller's page is worse than no line at all. Zero IS a
+ * number and is rendered — "0 views" is a true and useful thing to tell a
+ * seller, and the case it must not be confused with (the field is missing) is
+ * already `undefined` here.
+ */
+export function listingViewCount(
+  row: ListingEngagementFields | undefined
+): number | undefined {
+  const raw = row?.view_count;
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+}
+
+/**
+ * One listing's entry out of a batch answer, or `undefined`.
+ *
+ * The wire keys are STRINGS and an id with no listing is simply absent, so
+ * this is a lookup rather than an index: `batch.items[id]` would be a type
+ * error today and a silent `undefined` tomorrow.
+ */
+export function engagementFor(
+  batch: ListingEngagementBatch | undefined,
+  id: number
+): ListingEngagement | undefined {
+  return batch?.items[String(id)];
+}
+
+/**
+ * Lay an overlay entry over a row, so a card reads ONE object whatever its
+ * provenance.
+ *
+ * The overlay wins where it speaks, and it speaks about all three of its
+ * fields at once — it is the answer to a question that was actually asked on
+ * this reader's behalf, and the row (a search document, or a card serialized
+ * before the fields existed) is at best older and at worst silent. Where
+ * there is no overlay entry the row is returned UNCHANGED, by identity: a
+ * missing id, an overlay that has not loaded, and an overlay that failed are
+ * the same "we know nothing more than the row does", and none of them may
+ * fabricate a `false`.
+ */
+export function withEngagement(
+  row: ListingCard,
+  overlay: ListingEngagement | undefined
+): ListingCard {
+  if (overlay === undefined) return row;
+  return {
+    ...row,
+    viewed: overlay.viewed,
+    view_count: overlay.view_count,
+    is_favorited: overlay.is_favorited,
+  };
+}

package/src/model/queries.ts

@@ -5,11 +5,13 @@ import type { StapelApiError } from "@stapel/core";
 import type { ValidationBatchResult } from "@stapel/attributes-react";
 import type {
   ListingDetail,
+  ListingEngagementBatch,
   ListingPageParams,
   ListingStatusInfo,
   MyCounters,
   PaginatedListingCards,
 } from "../api/types.js";
+import { engagementIds } from "../api/types.js";
 import { useListingsApi } from "./context.js";
 import { listingsQueryKeys, pageKey } from "./queryKeys.js";
 
@@ -148,3 +150,42 @@ export function useValidateDraft(
     retry: false,
   });
 }
+
+/**
+ * The per-viewer ENGAGEMENT overlay for one page of ids, in one request.
+ *
+ * `AllowAny` upstream, so it joins the ungated regime described at the top of
+ * this file: a signed-out grid asks exactly the same question and is told
+ * `null` for both per-viewer flags. Gating it on the session substrate would
+ * make a shop window wait for a login bootstrap in order to decorate itself.
+ *
+ * ── Every failure mode here is a NO-OP, on purpose ────────────────────────
+ *
+ * `retry: false`, no error surface, and `enabled` false for an empty page.
+ * This read decorates a grid that has already rendered from somewhere else:
+ * if it 500s, times out, or is never wired at all, the cards must draw
+ * exactly as they drew before it existed. Retrying a decoration three times
+ * spends a person's connection on a flag, and an error banner over a working
+ * results page trades the thing they came for against the thing they did not
+ * ask about. `useEngagementOverlay` therefore reads only `data`, and the
+ * failure is available to a host that wants it and rendered by nobody.
+ *
+ * `placeholderData: keepPreviousData` for the paging case: a grid whose cards
+ * un-dim for a moment on every page change is reporting a state change that
+ * did not happen. The previous answer is still true about the previous ids,
+ * and `withEngagement` only ever reads the entries whose ids it asked for.
+ */
+export function useListingEngagement(
+  ids: readonly number[],
+  options?: { readonly enabled?: boolean }
+): UseQueryResult<ListingEngagementBatch, StapelApiError> {
+  const api = useListingsApi();
+  const wanted = engagementIds(ids);
+  return useQuery({
+    queryKey: listingsQueryKeys.engagement(wanted),
+    queryFn: ({ signal }) => api.engagement(wanted, { signal }),
+    enabled: (options?.enabled ?? true) && wanted.length > 0,
+    placeholderData: keepPreviousData,
+    retry: false,
+  });
+}

package/src/model/queryKeys.ts

@@ -11,6 +11,7 @@
  * produces a different request cannot silently reuse a page — the stale-page
  * bug (new filter, cached rows) is unwritable rather than merely avoided.
  */
+import { engagementIds } from "../api/types.js";
 import type { ListingPageParams } from "../api/types.js";
 
 /** The normalized page cursor a list read is keyed on. */
@@ -67,6 +68,18 @@ export const listingsQueryKeys: {
   allFavorites(): readonly ["listings", "my", "favorites"];
   /** Every published-card PAGE, same reason. */
   allLists(): readonly ["listings", "list"];
+  /**
+   * The per-viewer overlay for one page of ids.
+   *
+   * Keyed on the NORMALIZED list (`engagementIds`: sorted, de-duplicated,
+   * capped) and joined into one string, which is the same value the request
+   * sends. The doctrine at the top of this file applied to a batch read: two
+   * renders asking for the same ids in a different order are asking the
+   * identical question — the answer is a map keyed by id and carries no order
+   * of its own — so they must share one cache entry and cost one request.
+   * Keyed on the raw array they would cost two, per re-render, per grid.
+   */
+  engagement(ids: readonly number[]): readonly ["listings", "engagement", string];
 } = {
   all: [ROOT],
   list: (page) => [ROOT, "list", page],
@@ -80,4 +93,5 @@ export const listingsQueryKeys: {
   validateDraft: (id) => [ROOT, "validate-draft", id],
   allFavorites: () => [ROOT, "my", "favorites"],
   allLists: () => [ROOT, "list"],
+  engagement: (ids) => [ROOT, "engagement", engagementIds(ids).join(",")],
 };