@stapel/listings-react 0.25.0 → 0.25.2

package/src/headless/MyListings.tsx

@@ -22,6 +22,8 @@ import { useMyCounters } from "../model/queries.js";
 import { listingsQueryKeys, pageKey } from "../model/queryKeys.js";
 import { MY_LISTINGS_TABS, MY_LISTINGS_UNTABBED_STATUSES } from "../model/status.js";
 import type { MyListingsTab } from "../model/status.js";
+import { browserAddress, tabFromSearch } from "../model/tabAddress.js";
+import type { MyListingsAddress } from "../model/tabAddress.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { useMandateGate } from "./useMandateGate.js";
 
@@ -47,8 +49,26 @@ export interface MyListingsBag {
   readonly tab: MyListingsTab;
   readonly tabs: readonly MyListingsTab[];
   setTab(tab: MyListingsTab): void;
-  /** The three real counts. */
+  /** The three real counts, as the server reports them. */
   readonly counters: LoadState<MyCounters>;
+  /**
+   * The number to DRAW on each tab — the server's counter, raised to what is
+   * actually on screen.
+   *
+   * D407: a moderator-rejected listing was on the Drafts tab under a badge
+   * reading `0`. The two sets are grouped in two places — `my/counters`
+   * aggregates server-side, `MY_LISTINGS_TAB_STATUSES` decides which statuses
+   * a tab ASKS for — and any disagreement between them (a deployment running
+   * an older counter, a status added upstream, a grouping changed on one side)
+   * lands as a badge contradicting the rows underneath it.
+   *
+   * A count smaller than what a person can see is not a count, so the loaded
+   * rows are treated as evidence: for the OPEN tab the number is never below
+   * `rows.length`. It is a floor and not a replacement — the rows are one
+   * keyset page and the counter is the whole set, so the counter still wins
+   * whenever it is the larger of the two.
+   */
+  readonly tabCounts: LoadState<Readonly<Record<MyListingsTab, number>>>;
   /** The rows for the current tab. */
   readonly rows: LoadState<readonly MyListingCard[]>;
   /**
@@ -72,8 +92,23 @@ export interface UseMyListingsOptions {
   /** Replace the contract's own `my/listings` read — a deployment that keeps
    * its sellers' rows somewhere else. Absent: {@link defaultMyListingsSource}. */
   readonly source?: MyListingsSource;
+  /**
+   * Which tab to open when the ADDRESS names none. `?tab=drafts` wins over it
+   * — an address is a person's own statement about what they want to see, and
+   * a default cannot outrank one.
+   */
   readonly initialTab?: MyListingsTab;
   readonly limit?: number;
+  /**
+   * Where the open tab is kept. Default: the browser's own query string
+   * (`?tab=`), which is what makes `/account/listings?tab=drafts` open drafts
+   * and survive a reload — see `model/tabAddress.ts`.
+   *
+   * A host with a router passes its own binding. `NO_ADDRESS` opts out
+   * entirely, for a surface that mounts this hook somewhere the address is not
+   * about it (two dashboards on one page, a preview inside a modal).
+   */
+  readonly address?: MyListingsAddress;
 }
 
 export function useMyListings(
@@ -81,8 +116,13 @@ export function useMyListings(
 ): MyListingsBag {
   const gate = useMandateGate();
   const sessionReady = useActiveSessionReady();
+  // The address is read ONCE, at mount, and written on every change: this is
+  // the initial value of a control the person then operates, not a controlled
+  // input fed by the URL. (A host that navigates its own router to a different
+  // `?tab=` remounts the pane, which is the same thing.)
+  const address = options.address ?? browserAddress();
   const [tab, setTabState] = useState<MyListingsTab>(
-    options.initialTab ?? "active"
+    () => tabFromSearch(address.search) ?? options.initialTab ?? "active"
   );
   const [page, setPage] = useState<MyListingsParams>(
     options.limit !== undefined ? { limit: options.limit } : {}
@@ -130,6 +170,24 @@ export function useMyListings(
 
   const envelope = rowsQuery.data;
 
+  // D407, the floor: never a number smaller than the rows on screen. See
+  // `MyListingsBag.tabCounts`.
+  const tabCounts: LoadState<Readonly<Record<MyListingsTab, number>>> =
+    useMemo(() => {
+      if (counters.status === "error") return loadFailed(counters.error);
+      if (counters.data === undefined) return loadLoading();
+      const server = counters.data;
+      const visible = rows.status === "ready" ? rows.data.length : 0;
+      return loadReady(
+        Object.fromEntries(
+          MY_LISTINGS_TABS.map((one) => [
+            one,
+            one === tab ? Math.max(server[one], visible) : server[one],
+          ])
+        ) as Readonly<Record<MyListingsTab, number>>
+      );
+    }, [counters.status, counters.error, counters.data, rows, tab]);
+
   return {
     tab,
     tabs: MY_LISTINGS_TABS,
@@ -140,6 +198,9 @@ export function useMyListings(
       // down for its own keyset state.
       setPage(options.limit !== undefined ? { limit: options.limit } : {});
       setTabState(next);
+      // …and the address says which list is on screen, so a reload, a
+      // bookmark and a shared link all land on it.
+      (options.address ?? browserAddress()).setTab(next);
     },
     counters:
       counters.status === "error"
@@ -147,6 +208,7 @@ export function useMyListings(
         : counters.data !== undefined
           ? loadReady(counters.data)
           : loadLoading(),
+    tabCounts,
     rows,
     blockedRows,
     page,

package/src/i18n/es.ts

@@ -209,7 +209,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.favorites.load_failed": "No pudimos cargar tus favoritos",
   "listings.favorites.empty": "Todavía no has guardado nada",
   "listings.favorites.empty_hint":
-    "Toca el corazón en cualquier anuncio y te estará esperando aquí.",
+    "Toca «Guardar en favoritos» en cualquier anuncio y te estará esperando aquí.",
   "listings.favorites.sign_in_hint":
     "Los favoritos se guardan en tu cuenta, así que te siguen entre dispositivos.",
 

package/src/i18n/keys.ts

@@ -458,7 +458,7 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.favorites.load_failed": "We could not load your favourites",
   "listings.favorites.empty": "You have not saved anything yet",
   "listings.favorites.empty_hint":
-    "Tap the heart on any listing and it will be waiting here.",
+    "Tap 'Save to favourites' on any listing and it will be waiting here.",
   "listings.favorites.sign_in_hint":
     "Favourites are kept with your account, so they follow you between devices.",
 

package/src/i18n/ru.ts

@@ -232,7 +232,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.favorites.load_failed": "Не удалось загрузить избранное",
   "listings.favorites.empty": "Вы ещё ничего не сохранили",
   "listings.favorites.empty_hint":
-    "Нажмите на сердечко в любом объявлении — оно будет ждать здесь.",
+    "Нажмите «В избранное» в любом объявлении — оно будет ждать здесь.",
   "listings.favorites.sign_in_hint":
     "Избранное хранится в аккаунте, поэтому переходит с вами на другие устройства.",
 

package/src/index.ts

@@ -132,6 +132,14 @@ export {
 // ── model: the owner's own rows ──────────────────────────────────────────────
 export { defaultMyListingsSource } from "./model/mineSource.js";
 export type { MyListingsSource } from "./model/mineSource.js";
+export {
+  MY_LISTINGS_TAB_PARAM,
+  NO_ADDRESS,
+  browserAddress,
+  searchWithTab,
+  tabFromSearch,
+} from "./model/tabAddress.js";
+export type { MyListingsAddress } from "./model/tabAddress.js";
 export {
   myListingImages,
   myListingPrice,

package/src/model/tabAddress.ts

@@ -0,0 +1,103 @@
+/**
+ * The dashboard's open tab, IN THE ADDRESS.
+ *
+ * `<MyListingsPane>` kept its tab in component state, which is the same as
+ * keeping it nowhere: `/account/listings?tab=drafts` opened Active, a reload
+ * threw the tab away, and a seller who wanted to send somebody (or themselves,
+ * tomorrow) to their drafts had no address that meant "drafts". "Which of my
+ * three lists am I looking at" is exactly the kind of state a URL is for —
+ * `@stapel/search-react` says the same thing at length about its filters.
+ *
+ * ── Why this module and not a router ─────────────────────────────────────
+ *
+ * This pair carries no router and must not grow one: a package that reached
+ * for `react-router` would be unusable in a Next.js app and vice versa. So the
+ * address is read and written through the two DOM APIs every browser has, and
+ * the whole of that contact is here — three pure functions plus one guarded
+ * read/write pair, so a test can exercise the rules without a window and a
+ * host with its own router can pass {@link MyListingsAddress} instead.
+ *
+ * ── replace, not push ────────────────────────────────────────────────────
+ *
+ * Switching tab is a READ of your own dashboard, not a step in a flow. A
+ * `pushState` per tab would make Back walk Archive → Drafts → Active before it
+ * left the dashboard at all, which is the history churn `@stapel/search-react`
+ * documents for its own "a filter is a read" decision. `replaceState` keeps
+ * the address shareable and reloadable, which is the whole point, and leaves
+ * Back meaning "the page before this one".
+ */
+import { MY_LISTINGS_TABS } from "./status.js";
+import type { MyListingsTab } from "./status.js";
+
+/** The query parameter the tab lives in. */
+export const MY_LISTINGS_TAB_PARAM = "tab";
+
+/**
+ * The tab a query string names, or `undefined`.
+ *
+ * An unknown value is `undefined` and NOT an error: a link written by hand, a
+ * tab this build has dropped, or a `?tab=` some other component on the page
+ * owns must all fall back to the host's `initialTab` rather than throwing or
+ * opening an empty list.
+ */
+export function tabFromSearch(search: string): MyListingsTab | undefined {
+  const value = new URLSearchParams(search).get(MY_LISTINGS_TAB_PARAM);
+  if (value === null) return undefined;
+  return MY_LISTINGS_TABS.find((tab) => tab === value);
+}
+
+/**
+ * The same query string with the tab written into it.
+ *
+ * Every other parameter is preserved verbatim and in place: the dashboard is
+ * one component on somebody's page, and rewriting an address it does not own
+ * would drop whatever else is in it.
+ */
+export function searchWithTab(search: string, tab: MyListingsTab): string {
+  const params = new URLSearchParams(search);
+  params.set(MY_LISTINGS_TAB_PARAM, tab);
+  const next = params.toString();
+  return next.length > 0 ? `?${next}` : "";
+}
+
+/**
+ * The address binding. A host with a router passes its own; absent, the
+ * browser's is used and a non-DOM environment gets one that does nothing.
+ */
+export interface MyListingsAddress {
+  /** The current query string, `?`-prefixed or not — both parse. */
+  readonly search: string;
+  /** Write the tab. See the module note for why this replaces. */
+  setTab(tab: MyListingsTab): void;
+}
+
+/** An address that carries nothing and remembers nothing — SSR, and a host
+ * that opts out. */
+export const NO_ADDRESS: MyListingsAddress = {
+  search: "",
+  setTab: () => undefined,
+};
+
+/**
+ * The browser's own address, or {@link NO_ADDRESS} where there is no document.
+ *
+ * Read fresh on every call rather than captured: the host's router may have
+ * navigated since this component mounted, and a stale copy would write back
+ * an address that is no longer on screen.
+ */
+export function browserAddress(): MyListingsAddress {
+  if (typeof window === "undefined" || typeof window.history === "undefined") {
+    return NO_ADDRESS;
+  }
+  return {
+    search: window.location.search,
+    setTab: (tab) => {
+      const next = searchWithTab(window.location.search, tab);
+      window.history.replaceState(
+        window.history.state,
+        "",
+        `${window.location.pathname}${next}${window.location.hash}`
+      );
+    },
+  };
+}