@stapel/listings-react 0.26.0 → 0.27.0

package/src/default/movableCluster.tsx

@@ -0,0 +1,137 @@
+/**
+ * ONE CLUSTER, TWO PLACES ON THE PAGE — the same instance, moved.
+ *
+ * ── The ask this answers, and why the obvious shape does not ──────────────
+ *
+ * A listing page wants the reader's two verbs beside the title AND in the
+ * condensed bar that arrives when the title scrolls away (reference §24). A
+ * host cannot do that today: `<ListingDetailPane>` mounts its cluster at
+ * exactly one `actionsPlacement`, so a container that wants the second one
+ * mounts a `<ListingActions>` of its own — which is a SECOND
+ * `useFavoriteToggle` on one page, two hearts that agree only after a refetch,
+ * and two copies of a control whose geometry this pair exists to rule once.
+ *
+ * The shapes that do NOT close it, stated because each looks like it would:
+ *
+ *   a render prop handed the cluster ELEMENT
+ *       A React element is a description, not an instance. Rendered in two
+ *       places it mounts twice — exactly the defect, now with the pair's name
+ *       on it.
+ *
+ *   the host moving one element between two parents
+ *       React unmounts and remounts across a parent change: the hook state
+ *       goes, the DOM node is a different node, and an optimistic favourite
+ *       in flight is lost mid-write.
+ *
+ *   two mounts kept in step by lifting the state
+ *       Two controls, one state — and then the page has two `aria-pressed`
+ *       hearts, two focus targets and two things for a probe to count.
+ *
+ * ── What this does ────────────────────────────────────────────────────────
+ *
+ * The cluster is rendered ONCE, through a portal, into a `<div>` this hook
+ * owns. The page draws SLOTS — empty `display: contents` divs — wherever the
+ * cluster may sit, and the container element is `appendChild`-ed into whichever
+ * slot is currently on screen with the highest priority. Moving a DOM node
+ * between parents is not a React tree change, so:
+ *
+ *   - `<ListingActions>` (and everything under it) mounts exactly once;
+ *   - the favourite button is literally the SAME `HTMLElement` in both
+ *     placements — `test/detailActionsPlacements.test.tsx` holds the node
+ *     across the move and asserts identity, which is the only assertion that
+ *     can tell this apart from a well-behaved remount;
+ *   - a slot that unmounts hands the cluster back to the next one down,
+ *     rather than taking it off the page.
+ *
+ * `display: contents` on both the slot and the container is load-bearing: the
+ * cluster must remain a direct flex item of the heading row (it is laid out by
+ * `justify="space-between"`) and must stay absolutely positionable against the
+ * gallery's containing block in the overlay arm. A wrapper that generated a
+ * box would change both.
+ */
+import { useCallback, useEffect, useRef } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+/** Neither slot nor container may generate a box — see the file header. */
+const CONTENTS: CSSProperties = { display: "contents" };
+
+export interface MovableCluster {
+  /**
+   * True when there is a document to portal into. `false` under SSR, where
+   * the caller renders the cluster inline at its primary placement instead —
+   * a server render has no scrolling and therefore no second placement.
+   */
+  readonly portable: boolean;
+  /** Render the cluster ONCE, anywhere in the tree. Returns the portal. */
+  render(cluster: ReactNode): ReactNode;
+  /**
+   * A mount point. The highest `priority` currently on screen holds the
+   * cluster; when it goes, the next one down gets it back.
+   */
+  slot(priority: number, name: string): ReactElement;
+}
+
+export function useMovableCluster(enabled: boolean): MovableCluster {
+  const container = useRef<HTMLElement | null>(null);
+  if (enabled && container.current === null && typeof document !== "undefined") {
+    const host = document.createElement("div");
+    host.style.display = "contents";
+    host.setAttribute("data-listings-cluster-portal", "");
+    container.current = host;
+  }
+  const slots = useRef(new Map<number, HTMLElement>());
+  const refs = useRef(new Map<number, (node: HTMLElement | null) => void>());
+
+  /** Put the container in the highest-priority slot that is on the page. */
+  const settle = useCallback((): void => {
+    const host = container.current;
+    if (host === null) return;
+    let best: HTMLElement | undefined;
+    let bestPriority = -1;
+    for (const [priority, node] of slots.current) {
+      // `isConnected` matters during a commit that removes a slot: React may
+      // hand back a node it is about to drop, and appending into it would take
+      // the cluster off the page with it.
+      if (node.isConnected && priority > bestPriority) {
+        bestPriority = priority;
+        best = node;
+      }
+    }
+    if (best !== undefined && host.parentNode !== best) best.appendChild(host);
+  }, []);
+
+  // The belt. A slot's ref cleanup is what normally moves the cluster, but a
+  // subtree removed around it would leave the container detached with nothing
+  // to notice; this runs after every commit and repairs that in one comparison.
+  useEffect(settle);
+
+  const refFor = useCallback(
+    (priority: number): ((node: HTMLElement | null) => void) => {
+      let ref = refs.current.get(priority);
+      if (ref === undefined) {
+        ref = (node: HTMLElement | null): void => {
+          if (node === null) slots.current.delete(priority);
+          else slots.current.set(priority, node);
+          settle();
+        };
+        refs.current.set(priority, ref);
+      }
+      return ref;
+    },
+    [settle]
+  );
+
+  return {
+    portable: container.current !== null,
+    render: (cluster: ReactNode): ReactNode =>
+      container.current === null ? null : createPortal(cluster, container.current),
+    slot: (priority: number, name: string): ReactElement => (
+      <div
+        ref={refFor(priority)}
+        style={CONTENTS}
+        data-listings-cluster-slot={name}
+      />
+    ),
+  };
+}

package/src/headless/MyListings.tsx

@@ -49,13 +49,23 @@ import { useMandateGate } from "./useMandateGate.js";
  * `blockedRows` is fetched beside them, off the same route, narrowed to
  * whatever `MY_LISTINGS_UNTABBED_STATUSES` derives.
  *
- * That second read is also the fourth tab's COUNT (D407). `my/counters` has
- * three integers and no fourth, so the removed tab is counted from the rows it
- * holds — which is honest exactly because that read is unpaged and runs
- * whichever tab is open. The one thing it cannot describe is a page cap: a
- * seller with more takedowns than one page of `my/listings` would see the page
- * count and not the total, and there is no counter on the wire to check it
- * against (see `MyListingsBag.tabCounts`).
+ * That second read used to be the fourth tab's COUNT as well (D407):
+ * `my/counters` had three integers and no fourth, so the removed tab was
+ * counted from the rows it holds — honest, because that read is unpaged and
+ * runs whichever tab is open, and blind to exactly one thing: a page cap. A
+ * seller with more takedowns than one page of `my/listings` saw the page count
+ * and not the total, and there was no counter on the wire to check it against.
+ *
+ * **stapel-listings 0.22.4 answers it**: `MyCountersResponse.blocked`, required
+ * beside the other three, over the same owner scope and the same grouping. So
+ * the tab's number is the SERVER's now and the unpaged read is what it always
+ * was underneath — the removed tab's ROWS. The two consequences are both
+ * visible: the tab appears from the counter (a beat earlier, and without the
+ * seller's whole takedown page having to land first), and a seller with more
+ * takedowns than fit on a page is told how many there are rather than how many
+ * arrived. A deployment on a server older than 0.22.4 sends no `blocked` at
+ * all, and then the rows are the count again — degraded to the previous
+ * answer, never to a `0` (see `MyListingsBag.tabCounts`).
  */
 
 export interface MyListingsBag {
@@ -66,10 +76,16 @@ export interface MyListingsBag {
    * The server's three always; the removed one only where there is something
    * in it or the person asked for it by address. An empty "Taken down" tab is
    * a scare, and the seller it would scare is the one it has nothing to tell.
+   *
+   * "Something in it" is `counters.blocked` (stapel-listings 0.22.4) and no
+   * longer the unpaged takedown page: the two reads settle independently, and
+   * the one that decides whether a tab strip has three tabs or four should be
+   * the one that answers in three integers rather than the one that answers in
+   * a page of listings.
    */
   readonly tabs: readonly MyListingsTab[];
   setTab(tab: MyListingsTab): void;
-  /** The three real counts, as the server reports them. */
+  /** The four 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
@@ -89,8 +105,13 @@ export interface MyListingsBag {
    *
    * The second half: a takedown was in no tab and therefore in no number, so
    * a cabinet holding one read "Active 0 · Drafts 0 · Archived 0" over it.
-   * `removed` is counted from `blockedRows` — there is no server counter to
-   * read, and the rows are the only evidence on the wire.
+   * `removed` was counted from `blockedRows`, because there was no server
+   * counter to read and the rows were the only evidence on the wire. There is
+   * one now — `MyCountersResponse.blocked`, stapel-listings 0.22.4 — and it is
+   * what the fourth tab draws, under the same floor as the other three: the
+   * open tab's number is never below the rows on screen. `blockedRows` stays
+   * the FALLBACK for a deployment whose server predates the field, which is a
+   * count that is right up to a page and never a `0` over a visible row.
    */
   readonly tabCounts: LoadState<Readonly<Record<MyListingsTab, number>>>;
   /** The rows for the current tab — {@link MyListingsBag.blockedRows} while
@@ -206,8 +227,17 @@ export function useMyListings(
   // The takedown count, when it is known. Not a `0` while the read is in
   // flight: the tab strip is drawn off this number and a tab that appeared a
   // beat after the page settled would move the three beside it.
-  const blockedCount =
+  //
+  // The SERVER's integer first (stapel-listings 0.22.4), the unpaged page's
+  // length only where a deployment's backend predates it. `counters.data` is
+  // typed with `blocked` required, so the runtime check is the honest one and
+  // not a type-driven one: an older server answers 200 with three keys, and a
+  // `?? 0` there would print "Taken down 0" over a row the seller can see.
+  const rowsBlockedCount =
     blockedRows.status === "ready" ? blockedRows.data.length : undefined;
+  const serverBlockedCount =
+    typeof counters.data?.blocked === "number" ? counters.data.blocked : undefined;
+  const blockedCount = serverBlockedCount ?? rowsBlockedCount;
 
   // Paging belongs to the tab's own keyset read. The takedowns are fetched
   // unpaged on purpose, so the removed tab has nowhere to go and says so.
@@ -229,13 +259,23 @@ export function useMyListings(
             one === tab ? Math.max(server[one], visible) : server[one],
           ])
         ) as Readonly<Record<MyListingsCountedTab, number>>),
-        [MY_LISTINGS_REMOVED_TAB]: blockedCount ?? 0,
+        // The fourth tab takes the same floor as the other three: the server's
+        // number, raised to what is on screen while this tab is the open one.
+        // The counter and the unpaged page are two reads of one set and either
+        // may be the staler — a badge under its own rows is not a count.
+        [MY_LISTINGS_REMOVED_TAB]:
+          tab === MY_LISTINGS_REMOVED_TAB
+            ? Math.max(blockedCount ?? 0, visible)
+            : (blockedCount ?? 0),
       });
     }, [counters.status, counters.error, counters.data, rows, tab, blockedCount]);
 
   // The removed tab is drawn where it has something to say — or where the
   // address named it, so `?tab=removed` opens a real (if empty) tab rather
   // than an activeKey pointing at nothing.
+  //
+  // "Something to say" is the COUNTER since 0.22.4, so the tab arrives with
+  // `my/counters` rather than waiting for a page of takedowns to come back.
   const tabs: readonly MyListingsTab[] =
     removed || (blockedCount ?? 0) > 0 ? MY_LISTINGS_TABS : MY_LISTINGS_COUNTED_TABS;
 

package/src/model/status.ts

@@ -285,8 +285,8 @@ export function listingStatusView(
 }
 
 /**
- * The three tabs `my/counters` COUNTS, and the statuses each one folds
- * together.
+ * The three tabs whose ROWS come off a keyset page, and the statuses each one
+ * folds together.
  *
  * The grouping is the SERVER's (`views.my_counters`), copied here so a tab's
  * caption and its count cannot describe different sets: `active` includes
@@ -294,10 +294,17 @@ export function listingStatusView(
  * both because a listing in those states is something the owner is still
  * working on. A client that grouped them its own way would show "3 active"
  * over two rows.
+ *
+ * The name is about the SOURCE, not about the counter: `MyCountersResponse`
+ * carries four integers since stapel-listings 0.22.4 (`blocked` joined the
+ * three), and this is still the set a {@link MyListingsCountedTab} —
+ * `MyListingsSource`'s whole parameter type — may name. The removed tab reads
+ * its rows off `?status=blocked` directly and unpaged, so a host that
+ * implemented the seam before the fourth tab existed is never handed it.
  */
 export const MY_LISTINGS_COUNTED_TABS = ["active", "drafts", "archived"] as const;
 
-/** One of the three tabs `MyCountersResponse` carries a number for. */
+/** One of the three tabs a `MyListingsSource` is asked for. */
 export type MyListingsCountedTab = (typeof MY_LISTINGS_COUNTED_TABS)[number];
 
 const COUNTED_TAB_STATUSES: Readonly<
@@ -308,8 +315,9 @@ const COUNTED_TAB_STATUSES: Readonly<
   archived: ["archived", "paused", "expired", "sold"],
 };
 
-/** Which of the three COUNTED tabs a status belongs to, or `undefined` for
- * one the server's own counter groups nowhere — `blocked`, today. */
+/** Which of the three keyset-paged tabs a status belongs to, or `undefined`
+ * for one none of them folds in — `blocked`, today, which has a tab and a
+ * counter of its own and a different row source under it. */
 export function countedTabOf(
   status: ListingLifecycleStatus
 ): MyListingsCountedTab | undefined {
@@ -320,13 +328,16 @@ export function countedTabOf(
 }
 
 /**
- * The statuses the server's own counter groups nowhere — `blocked`, and
- * nothing else today.
+ * The statuses none of the three paged tabs folds in — `blocked`, and nothing
+ * else today.
  *
  * DERIVED, not written down a second time: a status added upstream and left
- * out of the counter groupings lands here automatically and gets shown, which
- * is the opposite of what a hardcoded `["blocked"]` would do the day it goes
- * stale.
+ * out of the tab groupings lands here automatically and gets shown, which is
+ * the opposite of what a hardcoded `["blocked"]` would do the day it goes
+ * stale. That the server now has a `blocked` COUNTER for the same set does not
+ * make the derivation redundant: the counter names one status and this names
+ * whatever the three groupings leave over, which is the set the fourth tab
+ * must ASK for.
  */
 export const MY_LISTINGS_UNTABBED_STATUSES: readonly ListingLifecycleStatus[] =
   LISTING_STATUSES.filter((status) => countedTabOf(status) === undefined);
@@ -350,12 +361,16 @@ export const MY_LISTINGS_UNTABBED_STATUSES: readonly ListingLifecycleStatus[] =
  * ── Why a fourth tab and not the archive ─────────────────────────────────
  *
  * Folding `blocked` into `archived` is the other shape this could take, and
- * it costs the count: `my/counters` has three integers and no fourth, so an
- * archive tab holding takedowns would read the server's `archived` number —
- * `0` — until the tab was opened and its rows could raise it. The fourth tab
- * is counted from its OWN read (`?status=blocked`, unpaged), so the number is
- * right while the seller is looking at a different tab, which is exactly the
- * moment D407 was measured at.
+ * it cost the count: when D407 was written `my/counters` had three integers
+ * and no fourth, so an archive tab holding takedowns would have read the
+ * server's `archived` number — `0` — until the tab was opened and its rows
+ * could raise it. The fourth tab was counted from its OWN read
+ * (`?status=blocked`, unpaged) so that the number was right while the seller
+ * was looking at a different tab, which is exactly the moment D407 was
+ * measured at. stapel-listings 0.22.4 puts `blocked` in the counter, so the
+ * number is the server's now and that read is only the tab's rows — but the
+ * property it was there to defend is the same one, and it is now defended by
+ * the wire instead of by a page.
  *
  * The archive keeps its meaning too, which is not nothing: "I put this away"
  * and "a moderator took this down" are not the same sentence and a tab that