@stapel/listings-react 0.25.10 → 0.27.0

package/src/default/notice.ts

@@ -0,0 +1,68 @@
+/**
+ * A one-line confirmation, spoken once — the message seam this skin uses and
+ * the reason it is not a new dependency.
+ *
+ * ── There is no fleet-wide toast primitive, and this does not invent one ──
+ *
+ * `@stapel/tokens-antd/skin` carries `ErrorAlert`, `EmptyState`,
+ * `GatedControl`, `SkinDialog` and `SkinConfirm` — every way a pair states a
+ * REFUSAL or asks a question — and nothing at all for "that worked". So the
+ * seam here is antd's own, which this package already renders through:
+ *
+ *   1. `App.useApp().message` when the host mounts antd's `<App>`, which is
+ *      the arrangement antd itself asks for — the notice then inherits the
+ *      host's `ConfigProvider` theme, its locale and its container;
+ *   2. antd's STATIC `message` otherwise, so a host that never mounted `<App>`
+ *      still gets the confirmation instead of silence.
+ *
+ * Outside an `<App>`, `App.useApp()` returns `{message: {}, …}` — antd's own
+ * default context — which is why the arm is chosen by asking whether the
+ * function is there rather than by asking whether a provider is. A version
+ * that assumed the context would have been a confirmation that worked in
+ * every test and on no deployment.
+ *
+ * ── And a toast is never the ONLY copy of a confirmation ──────────────────
+ *
+ * A toast is transient by construction: it appears for three seconds
+ * somewhere the person may not be looking, and on a phone it can land under a
+ * thumb. So every caller here also paints the same sentence where the gesture
+ * happened — `<ShareAction>` states "Link copied" inside the open menu, and
+ * the heart's state is on the heart. This is the AMPLIFIER, never the record.
+ * A future `SkinNotice` in the substrate replaces the body of this function
+ * and nothing else; the callers already speak in resolved sentences.
+ */
+import { useCallback } from "react";
+import { App, message as staticMessage } from "antd";
+
+/** Say one short sentence. Resolved copy — this is the skin, not a bag. */
+export type Notice = (text: string) => void;
+
+/**
+ * How long a confirmation stands, in seconds.
+ *
+ * Two, not antd's default three. Every notice this package raises confirms
+ * something the person can already SEE — a filled heart, a sentence standing
+ * in the open share menu — so it is an acknowledgement, not information, and
+ * an acknowledgement that outstays the gesture is a strip of chrome sitting
+ * over the page a thumb was about to press next.
+ */
+export const NOTICE_SECONDS = 2;
+
+export function useNotice(): Notice {
+  const app = App.useApp();
+  const contextual = app.message.success;
+  return useCallback(
+    (text: string): void => {
+      if (typeof contextual === "function") {
+        contextual(text, NOTICE_SECONDS);
+        return;
+      }
+      // No `<App>` above us. antd's static entry renders its own holder into
+      // the document, which is exactly right for a host that never opted in,
+      // and is a no-op on a server where there is no document to render into.
+      if (typeof document === "undefined") return;
+      staticMessage.success(text, NOTICE_SECONDS);
+    },
+    [contextual]
+  );
+}

package/src/headless/MyListings.tsx

@@ -20,8 +20,13 @@ import type { MyListingsSource } from "../model/mineSource.js";
 import { useListingsApi } from "../model/context.js";
 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 {
+  MY_LISTINGS_COUNTED_TABS,
+  MY_LISTINGS_REMOVED_TAB,
+  MY_LISTINGS_TABS,
+  MY_LISTINGS_UNTABBED_STATUSES,
+} from "../model/status.js";
+import type { MyListingsCountedTab, 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";
@@ -37,45 +42,87 @@ import { useMandateGate } from "./useMandateGate.js";
  * keeps the argument and the seam that came out of it.
  *
  * TWO reads, not one, and the second one is the point of this file's shape:
- * the three tabs are the SERVER's status groupings, and `blocked` — a
+ * the three counted tabs are the SERVER's status groupings, and `blocked` — a
  * moderation takedown — is in none of them, because `my/counters` counts it
  * in none of them. A dashboard that only ever asked for a tab's statuses
  * would hide exactly the listing whose owner most needs to know. So
  * `blockedRows` is fetched beside them, off the same route, narrowed to
  * whatever `MY_LISTINGS_UNTABBED_STATUSES` derives.
+ *
+ * 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 {
   readonly tab: MyListingsTab;
+  /**
+   * The tabs to DRAW, in order.
+   *
+   * 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
-   * actually on screen.
+   * actually on screen, plus the fourth tab's own.
    *
-   * 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.
+   * D407, twice over. The first half: 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.
    *
-   * 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.
+   * 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` 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. */
+  /** The rows for the current tab — {@link MyListingsBag.blockedRows} while
+   * the removed tab is open, and the tab's own keyset page otherwise. */
   readonly rows: LoadState<readonly MyListingCard[]>;
   /**
-   * The rows no tab folds in — a moderation takedown, today. Empty for
-   * almost every seller; when it is not, it is the most important thing on
-   * the screen. Never `failed` in a way that hides the tabs: this read is
-   * independent of `rows` and a skin renders it beside them.
+   * The rows the server's own counter folds into no tab — a moderation
+   * takedown, today; the removed tab's whole contents and its count. Empty
+   * for almost every seller; when it is not, it is the most important thing
+   * on the screen. Never `failed` in a way that hides the tabs: this read is
+   * independent of the tab's own and a skin renders it beside them.
    */
   readonly blockedRows: LoadState<readonly MyListingCard[]>;
   readonly page: MyListingsParams;
@@ -136,11 +183,18 @@ export function useMyListings(
     [injected, api]
   );
   const ready = sessionReady && gate.available;
+  // The fourth tab is served by `blockedQuery` below, not by the host's
+  // source: `MyListingsSource` is typed for the three counted tabs and a host
+  // that implemented it before D407 has no answer for a fourth.
+  const removed = tab === MY_LISTINGS_REMOVED_TAB;
+  const countedTab: MyListingsCountedTab = removed
+    ? MY_LISTINGS_COUNTED_TABS[0]
+    : (tab as MyListingsCountedTab);
 
   const rowsQuery = useQuery({
-    queryKey: listingsQueryKeys.mine(tab, pageKey(page)),
-    queryFn: ({ signal }) => source({ tab, page, signal }),
-    enabled: ready,
+    queryKey: listingsQueryKeys.mine(countedTab, pageKey(page)),
+    queryFn: ({ signal }) => source({ tab: countedTab, page, signal }),
+    enabled: ready && !removed,
     retry: false,
   });
 
@@ -155,12 +209,6 @@ export function useMyListings(
     retry: false,
   });
 
-  const rows: LoadState<readonly MyListingCard[]> = useMemo(() => {
-    if (rowsQuery.status === "error") return loadFailed(rowsQuery.error);
-    if (rowsQuery.data !== undefined) return loadReady(rowsQuery.data.items);
-    return loadLoading();
-  }, [rowsQuery.status, rowsQuery.error, rowsQuery.data]);
-
   const blockedRows: LoadState<readonly MyListingCard[]> = useMemo(() => {
     if (MY_LISTINGS_UNTABBED_STATUSES.length === 0) return loadReady([]);
     if (blockedQuery.status === "error") return loadFailed(blockedQuery.error);
@@ -168,9 +216,35 @@ export function useMyListings(
     return loadLoading();
   }, [blockedQuery.status, blockedQuery.error, blockedQuery.data]);
 
-  const envelope = rowsQuery.data;
+  const tabRows: LoadState<readonly MyListingCard[]> = useMemo(() => {
+    if (rowsQuery.status === "error") return loadFailed(rowsQuery.error);
+    if (rowsQuery.data !== undefined) return loadReady(rowsQuery.data.items);
+    return loadLoading();
+  }, [rowsQuery.status, rowsQuery.error, rowsQuery.data]);
+
+  const rows = removed ? blockedRows : tabRows;
+
+  // 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.
+  //
+  // 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;
 
-  // D407, the floor: never a number smaller than the rows on screen. See
+  // 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.
+  const envelope = removed ? undefined : rowsQuery.data;
+
+  // D407, the floor: never a number smaller than the rows on screen — and a
+  // number for the fourth tab, which the server counts nowhere. See
   // `MyListingsBag.tabCounts`.
   const tabCounts: LoadState<Readonly<Record<MyListingsTab, number>>> =
     useMemo(() => {
@@ -178,19 +252,36 @@ export function useMyListings(
       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) => [
+      return loadReady({
+        ...(Object.fromEntries(
+          MY_LISTINGS_COUNTED_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]);
+        ) as Readonly<Record<MyListingsCountedTab, number>>),
+        // 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;
 
   return {
     tab,
-    tabs: MY_LISTINGS_TABS,
+    tabs,
     setTab: (next) => {
       // A cursor belongs to ONE ordered candidate set. Carried across a tab
       // change it either bounces or honestly returns page four of a

package/src/headless/Share.tsx

@@ -0,0 +1,278 @@
+/**
+ * Sharing a listing — the verb a classified is judged on and this pair did
+ * not have.
+ *
+ * Measured on the live storefront (owner, 2026-09-06): **no share control of
+ * any kind**, on any surface. A person who wanted to send an offer to whoever
+ * they are buying it with had the address bar and nothing else, on a phone,
+ * where the address bar is the hardest thing on the screen to reach. Every
+ * reference classified answers this with one button.
+ *
+ * ── Two arms, and the device decides which ────────────────────────────────
+ *
+ * `navigator.share` is the whole answer where it exists: the platform's own
+ * sheet, with the person's own apps in it, in their own order. It exists on
+ * essentially every phone and on almost no desktop, which is why the second
+ * arm is not a fallback for old browsers but the DESKTOP rendering — a small
+ * menu with "copy the link" and the three networks a Russian-speaking
+ * marketplace actually gets traffic from.
+ *
+ * `native` is resolved in an EFFECT rather than during render, for the reason
+ * `cardGallery.ts`'s `useFinePointer` gives at length: a server render has no
+ * `navigator`, and a first client render that disagreed with it is a
+ * hydration mismatch on every listing page in the app. It opens `false` — the
+ * menu arm — because a menu that appears for one frame and is replaced by a
+ * button is invisible, while the reverse is a sheet that fails to open.
+ *
+ * ── The URL is the HOST'S, never `window.location` ────────────────────────
+ *
+ * A pair does not own routing (`@stapel/core`'s `ui.ts` argues it). The
+ * canonical address of a listing is a route the container built, so it
+ * arrives as {@link UseShareOptions.url} and is used verbatim. `location.href`
+ * is consulted ONLY when the host supplied nothing — which is honest for a
+ * bare mount and wrong the moment an app has a canonical URL, because the
+ * address bar on a SERP carries the query, the page, the scroll anchor and
+ * whatever tracking parameters the visitor arrived with, and none of that
+ * belongs in a link somebody sends to a friend.
+ *
+ * A RELATIVE `url` ("/l/7" — what every route seam in this fleet speaks) is
+ * resolved against the document's own base, so a host hands in the same path
+ * it hands `<ListingCard href>` and gets an absolute link out.
+ *
+ * ── Nothing here renders ──────────────────────────────────────────────────
+ *
+ * The hook returns hrefs and channel identifiers; the copy lives in the skin.
+ * A host drawing its own share menu gets the same three links and the same
+ * clipboard write without importing antd.
+ */
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { ReactElement, ReactNode } from "react";
+
+/**
+ * Where a share went. `"native"` is the platform sheet (which never says
+ * WHICH app the person picked — that is the sheet's privacy property, not a
+ * gap here), `"copy"` is the clipboard, and the three networks are the
+ * explicit links.
+ */
+export type ShareChannel = "native" | "copy" | "telegram" | "whatsapp" | "vk";
+
+/** The three networks, in the order the menu draws them. */
+export const SHARE_NETWORKS = ["telegram", "whatsapp", "vk"] as const;
+
+export type ShareNetwork = (typeof SHARE_NETWORKS)[number];
+
+/** One network's ready-made link. */
+export interface ShareLink {
+  readonly channel: ShareNetwork;
+  /** Absolute, already encoded. Rendered `target="_blank"` with
+   * `rel="noopener noreferrer"` — see `<ShareAction>` for why both. */
+  readonly href: string;
+}
+
+export interface ShareTarget {
+  /** The canonical, ABSOLUTE address of what is being shared. */
+  readonly url: string;
+  /** The listing's title. Empty is a real answer — an untitled listing is
+   * still shareable — and then the networks carry the link alone. */
+  readonly title?: string | undefined;
+}
+
+/**
+ * The three networks' share endpoints, as pure functions of the target.
+ *
+ * Separate from the hook and exported so the encoding is a thing a test can
+ * read rather than a thing a rendered `<a href>` implies. Each is the
+ * network's own documented endpoint:
+ *
+ *   Telegram  https://t.me/share/url?url=…&text=…
+ *   WhatsApp  https://wa.me/?text=…              (one field: title + url)
+ *   VK        https://vk.com/share.php?url=…&title=…
+ *
+ * `encodeURIComponent` on every field, without exception. A listing title is
+ * seller-supplied text — it contains `&`, `#`, `?` and emoji in the wild —
+ * and a title pasted raw into a query string does not merely render oddly, it
+ * silently truncates the URL the recipient receives at the first `&`.
+ */
+export function shareLinks(target: ShareTarget): readonly ShareLink[] {
+  const url = encodeURIComponent(target.url);
+  const title = target.title ?? "";
+  const text = encodeURIComponent(title);
+  // WhatsApp takes ONE field, so the title and the link travel together in
+  // it; the other two carry the address in its own parameter.
+  const whatsapp = encodeURIComponent(
+    title.length > 0 ? `${title} ${target.url}` : target.url
+  );
+  return [
+    { channel: "telegram", href: `https://t.me/share/url?url=${url}&text=${text}` },
+    { channel: "whatsapp", href: `https://wa.me/?text=${whatsapp}` },
+    { channel: "vk", href: `https://vk.com/share.php?url=${url}&title=${text}` },
+  ];
+}
+
+/**
+ * Resolve what the host handed in into an absolute address.
+ *
+ * Three cases and no guessing: an absolute URL is returned as it came, a path
+ * is resolved against the document's base, and nothing at all falls back to
+ * the address bar (see the file header for why that is the last resort and
+ * not the default).
+ */
+export function resolveShareUrl(url: string | undefined): string | undefined {
+  if (typeof window === "undefined") return url;
+  const base = window.document.baseURI;
+  if (url === undefined || url.length === 0) return window.location.href;
+  try {
+    return new URL(url, base).href;
+  } catch {
+    return url;
+  }
+}
+
+/** Is this environment able to open the platform's own share sheet? */
+export function hasNativeShare(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return typeof navigator.share === "function";
+}
+
+export interface UseShareOptions {
+  /** The canonical address, absolute or a path. Absent: the address bar,
+   * which is the honest answer only for a host with no route seam. */
+  readonly url?: string | undefined;
+  /** The listing's title — the sheet's heading and the networks' text. */
+  readonly title?: string | undefined;
+  /** A sentence under the title in the platform sheet (the price, say). */
+  readonly text?: string | undefined;
+  /** Analytics. Fired once per completed share, with the channel it went
+   * through; `"native"` never says which app, because the sheet does not
+   * tell the page. */
+  readonly onShared?: ((channel: ShareChannel) => void) | undefined;
+}
+
+export interface ShareBag {
+  /** The absolute address every arm shares. `undefined` only on a server. */
+  readonly url: string | undefined;
+  /** Does this device have the platform's own sheet? Settles in an effect —
+   * see the file header. */
+  readonly native: boolean;
+  /** The three networks' links, already encoded. */
+  readonly links: readonly ShareLink[];
+  /**
+   * The clipboard write LANDED, and this is what the confirmation is drawn
+   * from. It clears itself after {@link SHARE_COPIED_MS} so a menu reopened a
+   * minute later is not still congratulating the person.
+   */
+  readonly copied: boolean;
+  /** The clipboard refused (no permission, an insecure origin, a browser
+   * without the API). Stated, never swallowed: a person who pressed "copy"
+   * and pastes nothing has to be told the press did not work. */
+  readonly copyFailed: boolean;
+  /** Open the platform sheet. A no-op where there is none — callers branch on
+   * {@link ShareBag.native} rather than discovering it here. */
+  shareNatively(): void;
+  /** Write the address to the clipboard. */
+  copy(): void;
+  /** Report a network link the person actually followed. The anchor does the
+   * navigating; this is the analytics half. */
+  report(channel: ShareChannel): void;
+}
+
+/** How long the "copied" confirmation stands. Long enough to read, short
+ * enough that a reopened menu is not still showing it. */
+export const SHARE_COPIED_MS = 2400;
+
+export function useShare(options: UseShareOptions = {}): ShareBag {
+  const { url: given, title, text, onShared } = options;
+  const [native, setNative] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const [copyFailed, setCopyFailed] = useState(false);
+
+  // See the header: resolved in an effect so a server render and the
+  // hydration pass that must agree with it draw the same arm.
+  useEffect(() => {
+    setNative(hasNativeShare());
+  }, []);
+
+  const url = useMemo(() => resolveShareUrl(given), [given]);
+  const links = useMemo(
+    () => (url === undefined ? [] : shareLinks({ url, title })),
+    [url, title]
+  );
+
+  useEffect(() => {
+    if (!copied) return undefined;
+    const timer = setTimeout(() => {
+      setCopied(false);
+    }, SHARE_COPIED_MS);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [copied]);
+
+  const report = useCallback(
+    (channel: ShareChannel): void => {
+      onShared?.(channel);
+    },
+    [onShared]
+  );
+
+  const shareNatively = useCallback((): void => {
+    if (url === undefined) return;
+    const share = typeof navigator === "undefined" ? undefined : navigator.share;
+    if (typeof share !== "function") return;
+    // The rejection a share sheet ALWAYS produces is `AbortError` — the
+    // person closed it — and that is not a failure to report. Nothing is
+    // said either way; the sheet is the feedback.
+    void Promise.resolve(
+      share.call(navigator, {
+        url,
+        ...(title !== undefined && title.length > 0 ? { title } : {}),
+        ...(text !== undefined && text.length > 0 ? { text } : {}),
+      })
+    )
+      .then(() => {
+        report("native");
+      })
+      .catch(() => undefined);
+  }, [url, title, text, report]);
+
+  const copy = useCallback((): void => {
+    if (url === undefined) return;
+    setCopyFailed(false);
+    const clipboard =
+      typeof navigator === "undefined" ? undefined : navigator.clipboard;
+    if (clipboard === undefined || typeof clipboard.writeText !== "function") {
+      setCopyFailed(true);
+      return;
+    }
+    void Promise.resolve(clipboard.writeText(url))
+      .then(() => {
+        setCopied(true);
+        report("copy");
+      })
+      .catch(() => {
+        setCopyFailed(true);
+      });
+  }, [url, report]);
+
+  return {
+    url,
+    native,
+    links,
+    copied,
+    copyFailed,
+    shareNatively,
+    copy,
+    report,
+  };
+}
+
+/** Renderless: the bag, handed to a render prop — the shape every headless
+ * component in this pair takes. */
+export function Share(
+  props: UseShareOptions & {
+    children: (bag: ShareBag) => ReactNode;
+  }
+): ReactElement {
+  const bag = useShare(props);
+  return <>{props.children(bag)}</>;
+}

package/src/i18n/es.ts

@@ -77,10 +77,23 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.card.untitled": "Anuncio sin título",
   "listings.card.sign_in": "Iniciar sesión",
   "listings.card.photos": "Fotos de este anuncio",
+  "listings.card.photo_counter": "{index} de {total}",
   "listings.card.price_was": "Antes",
   "listings.card.price_dropped": "El precio ha bajado",
   "listings.card.price_raised": "El precio ha subido",
 
+  "listings.share.action": "Compartir",
+  "listings.share.copy": "Copiar enlace",
+  "listings.share.copied": "Enlace copiado",
+  "listings.share.copy_failed":
+    "No pudimos copiar el enlace — cópialo de la barra de direcciones",
+  "listings.share.telegram": "Telegram",
+  "listings.share.whatsapp": "WhatsApp",
+  "listings.share.vk": "VK",
+  "listings.favorite.added": "Añadido a favoritos",
+  "listings.favorite.removed": "Quitado de favoritos",
+  "listings.favorite.count": "{count} lo han guardado",
+
   "listings.detail.loading": "Cargando el anuncio…",
   "listings.detail.load_failed": "No pudimos cargar este anuncio",
   "listings.detail.retry": "Reintentar",
@@ -175,6 +188,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.mine.tab.active": "Activos",
   "listings.mine.tab.drafts": "Borradores",
   "listings.mine.tab.archived": "Archivo",
+  "listings.mine.tab.removed": "Retirados",
   "listings.mine.loading": "Cargando tus anuncios…",
   "listings.mine.load_failed": "No pudimos cargar tus anuncios",
   "listings.mine.empty": "Aquí todavía no hay nada",
@@ -183,6 +197,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.mine.empty.active": "No tienes nada publicado ni en revisión",
   "listings.mine.empty.drafts": "Sin borradores: lo que empieces aparecerá aquí",
   "listings.mine.empty.archived": "Nada archivado, pausado, caducado ni vendido todavía",
+  "listings.mine.empty.removed": "Moderación no ha retirado nada tuyo",
   "listings.mine.blocked.title":
     "Moderación retiró {count} de tus anuncios",
   "listings.mine.blocked.title.one": "Moderación retiró uno de tus anuncios",
@@ -203,6 +218,8 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.mine.delete_confirm_title": "¿Borrar este anuncio?",
   "listings.mine.delete_confirm_body":
     "Desaparece de tu panel y no se puede recuperar. Archivarlo lo conserva.",
+  "listings.mine.delete_confirm_body.final":
+    "Desaparece de tu panel y no se puede recuperar.",
 
   "listings.favorites.title": "Favoritos",
   "listings.favorites.loading": "Cargando tus favoritos…",
@@ -222,6 +239,17 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "error.400.listing_draft_meta_too_large":
     "El borrador es demasiado grande (máximo {max_bytes} bytes). Quita parte de los datos y guarda de nuevo.",
 
+  // stapel-listings 0.22.3: the features_draft WRITE now accepts the shape a
+  // listing READ returns. These three are the refusals for a body that is
+  // neither — read by whoever is wiring the integration, so each names the
+  // shape it wanted instead of advising "try again".
+  "error.400.listing_features_draft_shape":
+    "features_draft debe ser un objeto con los slugs de las características como claves, o la lista de objetos de característica que devuelve la lectura del anuncio (cada uno con su propio «slug»). Llegó: {got_type}. Ejemplo de la forma de objeto aceptada: {example}",
+  "error.400.listing_features_draft_unknown_slug":
+    "Cada elemento de una lista features_draft debe llevar su propio «slug» no vacío — el que la lectura del anuncio guarda en ese elemento — para poder archivarlo bajo la característica correcta. El elemento en el índice {index} no lo tiene. Ejemplo: {example}",
+  "error.400.listing_features_draft_value_shape":
+    "features_draft['{slug}'] debe ser a su vez un objeto de la forma {{\"type\": <tipo de característica>, \"value\": <valor de característica>}}. Llegó: {got_type}. Ejemplo: {example}",
+
   "listings.blocked.sign_in": "Inicia sesión para hacer esto",
   "listings.blocked.guest":
     "Esta cuenta todavía no puede hacerlo — termina de configurarla primero",

package/src/i18n/generated/errors.es.gen.ts

@@ -8,7 +8,7 @@ import type { ListingsErrorCode } from "./errors.gen.js";
 /**
  * `es` texts for the backend error codes this catalog carries.
  *
- * PARTIAL, and deliberately typed to say so: 27 key(s) owned by
+ * PARTIAL, and deliberately typed to say so: 30 key(s) owned by
  * stapel_attributes, stapel_listings are absent, because that owner ships no locale catalog
  * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
  * artifact via the en bundle; the pair layers its own authored `es`