@stapel/listings-react 0.25.1 → 0.25.3

package/src/default/MyListingsPane.tsx

@@ -63,6 +63,7 @@ import { useListingActions } from "../headless/ListingActions.js";
 import { myListingTitle, neverSubmitted } from "../model/mine.js";
 import { listingStatusView } from "../model/status.js";
 import type { MyListingsTab } from "../model/status.js";
+import type { MyListingsAddress } from "../model/tabAddress.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { ListingPhoto } from "./ListingPhoto.js";
 import { SignInLink } from "./SignInLink.js";
@@ -358,6 +359,17 @@ export interface MyListingsPaneProps extends ThemeModeProp, SignInCtaProp {
   /** How the host gets the caller's own rows. Absent: the contract's own
    * `GET my/listings/`, which is what a storefront wants. */
   readonly source?: MyListingsSource;
+  /**
+   * Which tab to open when the ADDRESS names none — `?tab=drafts` wins over
+   * it. See `model/tabAddress.ts`.
+   */
+  readonly initialTab?: MyListingsTab;
+  /**
+   * Where the open tab is kept. Default: the browser's own `?tab=`, so
+   * `/account/listings?tab=drafts` opens drafts and a reload keeps it. A host
+   * with a router passes its own binding; `NO_ADDRESS` opts out.
+   */
+  readonly address?: MyListingsAddress;
   /**
    * Open the composer on one of these listings. ABSENT IS A REAL ANSWER: the
    * Edit button then states that this app has no editing screen instead of
@@ -392,9 +404,11 @@ export interface MyListingsPaneProps extends ThemeModeProp, SignInCtaProp {
 export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
   const t = useT();
   const tPlural = useTPlural();
-  const bag = useMyListings(
-    props.source !== undefined ? { source: props.source } : {}
-  );
+  const bag = useMyListings({
+    ...(props.source !== undefined ? { source: props.source } : {}),
+    ...(props.initialTab !== undefined ? { initialTab: props.initialTab } : {}),
+    ...(props.address !== undefined ? { address: props.address } : {}),
+  });
   // ONE confirmation for the whole list, keyed by the row that asked — not one
   // mounted dialog per row.
   const [removingId, setRemovingId] = useState<number | null>(null);
@@ -483,7 +497,7 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
             label: (
               <>
                 {t(TAB_LABEL[tab])}
-                {matchLoad(bag.counters, {
+                {matchLoad(bag.tabCounts, {
                   loading: () => null,
                   // A count we could not fetch is not zero. The number is
                   // simply absent and the failure is stated once, below.
@@ -492,12 +506,16 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
                   // danger token and "Active 2" is not a warning. It also
                   // keeps the tab short enough that three of them fit on a
                   // phone instead of collapsing into an overflow menu.
-                  ready: (counters) => (
+                  //
+                  // `tabCounts`, not `counters`: the badge is never allowed to
+                  // read lower than the rows underneath it (D407 — a
+                  // moderator-rejected listing sat in Drafts under a `0`).
+                  ready: (counts) => (
                     <Typography.Text
                       type="secondary"
                       data-testid={`listings-mine-count-${tab}`}
                     >
-                      {` ${String(counters[tab])}`}
+                      {` ${String(counts[tab])}`}
                     </Typography.Text>
                   ),
                 })}

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/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}`
+      );
+    },
+  };
+}