@stapel/listings-react 0.25.10 → 0.26.0

package/src/default/ListingSerpCard.tsx

@@ -89,6 +89,11 @@ import { useEngagedListing } from "../headless/Engagement.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { PriceTrendIcon } from "./icons.js";
 import { FavoriteHeart } from "./favorite.js";
+import {
+  LISTING_ACTIONS_CLASS,
+  LISTING_ACTIONS_OVERLAY_CLASS,
+  LISTING_CARD_ACTION_CLASS,
+} from "./actionRow.js";
 import { CardBadges, CardSpecLine } from "./CardBadges.js";
 import {
   CARD_FRAME_CLASS,
@@ -220,8 +225,13 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   // Already seen — `false` for every response that carries no such field.
   const viewed = isListingViewed(listing);
 
+  /* The rail is what the CONTAINER put there — "call", "write". The heart
+     left it in this wave and now sits on the photograph (see `heartOverlay`),
+     which is where every reference classified's phone SERP has it and where a
+     thumb already is; the rail is at the far end of a line of text, three
+     glances away from the picture a person is actually looking at. */
   const rail =
-    props.actionsRail !== undefined || props.showFavorite !== false ? (
+    props.actionsRail !== undefined ? (
       <Flex
         vertical
         align="flex-end"
@@ -230,20 +240,36 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
         data-testid="listings-serp-actions"
       >
         {props.actionsRail}
-        {props.showFavorite === false ? null : (
-          <FavoriteHeart
-            listingId={listing.id}
-            favorited={listing.is_favorited}
-            testId="listings-serp-favorite"
-            {...(props.blockedReason !== undefined
-              ? { blockedReason: props.blockedReason }
-              : {})}
-            {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
-          />
-        )}
       </Flex>
     ) : null;
 
+  /* THE HEART, ON THE PHOTOGRAPH. Top-trailing: the strip's dots own the
+     bottom centre and its "3 of 16" counter owns the bottom trailing corner.
+     Outside every anchor, as it has always been — a link may not contain a
+     control — and `stopPropagation` on the bubble phase so a press that
+     somehow reached the card would still save rather than navigate. */
+  const heartOverlay =
+    props.showFavorite === false ? null : (
+      <div
+        className={`${LISTING_ACTIONS_CLASS} ${LISTING_ACTIONS_OVERLAY_CLASS}`}
+        data-testid="listings-serp-favorite-overlay"
+        onClick={(event) => {
+          event.stopPropagation();
+        }}
+      >
+        <FavoriteHeart
+          listingId={listing.id}
+          favorited={listing.is_favorited}
+          testId="listings-serp-favorite"
+          className={LISTING_CARD_ACTION_CLASS}
+          {...(props.blockedReason !== undefined
+            ? { blockedReason: props.blockedReason }
+            : {})}
+          {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
+        />
+      </div>
+    );
+
   return (
     <SkinTheme
       surface="bare"
@@ -289,6 +315,7 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
                 title={title.length > 0 ? title : String(listing.id)}
                 testId="listings-serp-photos"
               />
+              {heartOverlay}
             </div>
 
             <div className={CARD_MAIN_CLASS}>

package/src/default/MyListingsPane.tsx

@@ -15,12 +15,19 @@
  *    listing is offline, or never tell them their edit is being screened.
  *    `moderation_status` is on the owner card, so the row reads the real
  *    value rather than the `"approved"` stand-in it used before 0.7.0.
- * 2. **Takedowns are not in a tab.** The three tabs are the SERVER's status
- *    groupings and `blocked` is in none of them, because `my/counters` counts
- *    it in none of them. Folding it into one would make a tab's rows and its
- *    badge describe different sets; leaving it out entirely would hide the
- *    one listing whose owner most needs to know. So it sits above the tabs,
- *    where it cannot be missed.
+ * 2. **A takedown gets a tab of its own, and a count (D407).** The three
+ *    tabs are the SERVER's status groupings and `blocked` is in none of them,
+ *    because `my/counters` counts it in none of them — so a cabinet holding a
+ *    listing a moderator had pulled read "Active 0 · Drafts 0 · Archived 0"
+ *    over it, and said beside that that nothing of the seller's was live. The
+ *    row was on the page (in a block above the tabs) and in no tab and in no
+ *    number, and a person reads the numbers.
+ *
+ *    So the takedowns are the fourth tab, counted from their own read — see
+ *    `model/status.ts` for why a fourth tab and not the archive. The block
+ *    above the tabs stays as one LINE, without the rows: a takedown must not
+ *    need a click to be discovered, and printing the same row twice on one
+ *    screen is not the way to say so.
  * 3. **An empty tab says which emptiness it is.** "No drafts" and "nothing
  *    sold yet" are different sentences and one generic "nothing here" is
  *    neither.
@@ -85,6 +92,7 @@ const TAB_LABEL: Readonly<Record<MyListingsTab, string>> = {
   active: LISTINGS_I18N_KEYS.mineTabActive,
   drafts: LISTINGS_I18N_KEYS.mineTabDrafts,
   archived: LISTINGS_I18N_KEYS.mineTabArchived,
+  removed: LISTINGS_I18N_KEYS.mineTabRemoved,
 };
 
 /** One empty sentence per tab — see the header, point 3. */
@@ -92,6 +100,7 @@ const TAB_EMPTY: Readonly<Record<MyListingsTab, string>> = {
   active: LISTINGS_I18N_KEYS.mineEmptyActive,
   drafts: LISTINGS_I18N_KEYS.mineEmptyDrafts,
   archived: LISTINGS_I18N_KEYS.mineEmptyArchived,
+  removed: LISTINGS_I18N_KEYS.mineEmptyRemoved,
 };
 
 /** The thumbnail column. A photo marketplace whose seller dashboard is a
@@ -452,12 +461,19 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
   // 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);
-  const removal = useListingActions(
-    removingId ?? 0,
+  const removingRow =
     bag.rows.status === "ready"
-      ? bag.rows.data.find((row) => row.id === removingId)?.status
-      : undefined
-  );
+      ? bag.rows.data.find((row) => row.id === removingId)
+      : undefined;
+  const removal = useListingActions(removingId ?? 0, removingRow?.status, {
+    // The SERVER's answer for THIS row, exactly as the row's own controls
+    // take it. Without it this hook fell back to the mirror, and the mirror
+    // is a table about a status rather than about a listing — which is the
+    // difference between "a sold listing may be archived" and "this one may".
+    ...(removingRow?.available_transitions !== undefined
+      ? { available: removingRow.available_transitions }
+      : {}),
+  });
 
   const paged = bag.prevPage.available || bag.nextPage.available;
 
@@ -501,35 +517,37 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
           />
         ) : (
           <>
-        {/* The rows no tab folds in — see the header, point 2. Rendered
-            only when there are some: an empty takedown section is a scare,
-            and a failure to CHECK is not the same as "none", so it says so. */}
-        {matchList(bag.blockedRows, {
-          loading: () => null,
-          failed: () => (
-            <Typography.Text
-              type="secondary"
-              data-testid="listings-mine-takedowns-failed"
-            >
-              {t(LISTINGS_I18N_KEYS.mineBlockedLoadFailed)}
-            </Typography.Text>
-          ),
-          empty: () => null,
-          ready: (rows) => (
-            <Flex vertical gap={spacing[2]} data-testid="listings-mine-takedowns">
-              <Typography.Text type="warning" strong>
-                {tPlural(LISTINGS_I18N_KEYS.mineBlockedTitle, {
-                  count: rows.length,
-                })}
-              </Typography.Text>
-              <List
-                dataSource={[...rows]}
-                rowKey={(row) => row.id}
-                renderItem={renderRow}
-              />
-            </Flex>
-          ),
-        })}
+        {/* The takedowns, announced above the tabs — see the header, point 2.
+            The LINE only: the rows themselves are the fourth tab, and this
+            says how many there are without waiting for a click. Rendered only
+            when there are some (an empty takedown section is a scare) and not
+            while that tab is open (nobody needs telling twice); a failure to
+            CHECK is not the same as "none", so that says so. */}
+        {bag.tab === "removed"
+          ? null
+          : matchList(bag.blockedRows, {
+              loading: () => null,
+              failed: () => (
+                <Typography.Text
+                  type="secondary"
+                  data-testid="listings-mine-takedowns-failed"
+                >
+                  {t(LISTINGS_I18N_KEYS.mineBlockedLoadFailed)}
+                </Typography.Text>
+              ),
+              empty: () => null,
+              ready: (rows) => (
+                <Typography.Text
+                  type="warning"
+                  strong
+                  data-testid="listings-mine-takedowns"
+                >
+                  {tPlural(LISTINGS_I18N_KEYS.mineBlockedTitle, {
+                    count: rows.length,
+                  })}
+                </Typography.Text>
+              ),
+            })}
 
         <Tabs
           activeKey={bag.tab}
@@ -553,11 +571,13 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
                   // phone instead of collapsing into an overflow menu.
                   //
                   // `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`).
+                  // read lower than the rows underneath it, and the fourth tab
+                  // has no server counter at all (D407 — a moderator-rejected
+                  // listing sat in Drafts under a `0`, and a taken-down one
+                  // under no number whatever).
                   ready: (counts) => (
                     <Typography.Text
-                      type="secondary"
+                      type={tab === "removed" ? "warning" : "secondary"}
                       data-testid={`listings-mine-count-${tab}`}
                     >
                       {` ${String(counts[tab])}`}
@@ -680,11 +700,24 @@ export function MyListingsPane(props: MyListingsPaneProps): ReactElement {
           </>
         )}
 
+        {/* THE PROMISE IS ONLY MADE WHERE IT CAN BE KEPT.
+            "Archiving keeps it" is a real alternative to offer somebody about
+            to delete a live listing, and an insult to somebody deleting from
+            the archive — measured on the phone walk: the archive tab's own
+            delete dialog promised the archive to a person already standing in
+            it. So the sentence follows the ROW's state rather than the
+            wording, and the state that decides it is the one the seller would
+            have to act on: whether `archived` is a move this listing still
+            has. Archived, sold and taken-down rows have spent it. */}
         <SkinConfirm
           open={removingId !== null}
           danger
           title={t(LISTINGS_I18N_KEYS.mineDeleteConfirmTitle)}
-          body={t(LISTINGS_I18N_KEYS.mineDeleteConfirmBody)}
+          body={t(
+            removal.moves.some((move) => move.to === "archived")
+              ? LISTINGS_I18N_KEYS.mineDeleteConfirmBody
+              : LISTINGS_I18N_KEYS.mineDeleteConfirmBodyFinal
+          )}
           confirmLabel={t(LISTINGS_I18N_KEYS.mineDelete)}
           confirming={removal.inFlight}
           data-testid="listings-mine-delete-confirm"

package/src/default/ShareAction.tsx

@@ -0,0 +1,260 @@
+/**
+ * `<ShareAction>` — "share", the verb the storefront did not have.
+ *
+ * Measured by the owner on the live deployment (2026-09-06): **no share
+ * control anywhere in the product.** Not a badly placed one, not one behind a
+ * menu — none. The only way to send somebody a listing was the address bar,
+ * which on a phone is the hardest thing on the screen to reach and which
+ * carries the SERP's query string, the page anchor and whatever tracking
+ * parameters the visitor arrived with.
+ *
+ * ── One control, two renderings, and the DEVICE picks ─────────────────────
+ *
+ * Where `navigator.share` exists — which is every phone and almost no desktop
+ * — the press opens the PLATFORM's own sheet: the person's own apps, in their
+ * own order, including the ones we have never heard of. A library that drew
+ * its own list of four networks on a phone would be offering a worse version
+ * of something the operating system already does better.
+ *
+ * Where it does not, the press opens a small menu: copy the link, and the
+ * three networks a Russian-speaking marketplace actually receives traffic
+ * from. This is the DESKTOP rendering, not a fallback for old browsers, which
+ * is why it is built rather than apologised for.
+ *
+ * ── The menu is a Popover, and that is an exception with an argument ──────
+ *
+ * `stapel/no-tooltip-in-skin` bans `Popover` because of what a hover-triggered
+ * one does: it hides text a touch device can never reveal, and it anchors that
+ * text to a disabled control that swallows the events it needs. Neither
+ * applies here and both are structurally impossible:
+ *
+ *  - the trigger is `"click"` ONLY — no hover arm at all, so a thumb and a
+ *    cursor reach it by exactly the same gesture;
+ *  - the anchor is a live, enabled, focusable button;
+ *  - nothing is EXPLAINED in the overlay. It holds four controls. A menu is
+ *    the shape this content has had since menus existed, and the alternative
+ *    — four buttons standing permanently beside the title — is the "24 copies
+ *    of one sentence" defect that `GateReasonPopover` was written to end,
+ *    wearing a different hat.
+ *
+ * ── The word disappears on a phone; the NAME never does ───────────────────
+ *
+ * `aria-label` carries the verb in every arm and at every width. What the
+ * media query drops is the painted word beside the glyph, because at 390px
+ * the action row shares a line with a heart and a price. A screen reader
+ * announces the same verb on both.
+ *
+ * ── Every outbound link is `noopener noreferrer` ──────────────────────────
+ *
+ * `target="_blank"` without `rel="noopener"` hands the opened page a live
+ * `window.opener` handle to the storefront's tab, which is a one-line
+ * navigation hijack; `noreferrer` keeps the visitor's exact listing URL out of
+ * the network's referer log. Both, on all three, without exception.
+ */
+import { useCallback, useEffect, useState } from "react";
+import type { CSSProperties, ReactElement } from "react";
+import { Flex, Typography } from "antd";
+// eslint-disable-next-line stapel/no-tooltip-in-skin -- a MENU, not a hover explanation: trigger is click-only (a thumb and a cursor use one gesture), the anchor is a live enabled button, and the overlay holds four controls rather than a sentence. See this file's header.
+import { Popover } from "antd";
+import { SkinButton as Button, ErrorAlert } from "@stapel/tokens-antd/skin";
+import { useT } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { useShare } from "../headless/Share.js";
+import type { ShareChannel, ShareNetwork } from "../headless/Share.js";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import {
+  LISTING_ACTIONS_STYLE_HREF,
+  LISTING_ACTION_CLASS,
+  LISTING_ACTION_LABEL_CLASS,
+  actionRowCss,
+} from "./actionRow.js";
+import { LinkIcon, ShareIcon } from "./icons.js";
+import { useNotice } from "./notice.js";
+
+/** Which sentence names each network row. */
+const NETWORK_LABEL: Readonly<Record<ShareNetwork, string>> = {
+  telegram: LISTINGS_I18N_KEYS.shareTelegram,
+  whatsapp: LISTINGS_I18N_KEYS.shareWhatsapp,
+  vk: LISTINGS_I18N_KEYS.shareVk,
+};
+
+export interface ShareActionProps {
+  /**
+   * The listing's CANONICAL address — the route the container built, absolute
+   * or a path. Given, it is what every arm shares and `window.location` is
+   * never consulted; see `useShare` for why that distinction is the whole
+   * point of the prop.
+   */
+  readonly url?: string;
+  /** The listing's title: the platform sheet's heading and the networks'
+   * text. */
+  readonly title?: string;
+  /** A line under the title in the platform sheet — the price, typically. */
+  readonly text?: string;
+  /** Analytics, once per completed share. `"native"` never names the app the
+   * person chose, because the platform sheet does not tell the page. */
+  readonly onShared?: (channel: ShareChannel) => void;
+  /** This surface's own test id, so a screen holding a card and a listing
+   * page hands a test one element per name. Default `listings-share`. */
+  readonly testId?: string;
+  /**
+   * `"circle"` for the glyph pinned to the corner of a photograph (no room
+   * for a word, and the heart beside it is a circle); `"default"` (the
+   * default) draws the word beside the glyph wherever the viewport has room
+   * for it.
+   */
+  readonly shape?: "default" | "circle";
+  readonly style?: CSSProperties;
+}
+
+export function ShareAction(props: ShareActionProps): ReactElement {
+  const t = useT();
+  const testId = props.testId ?? "listings-share";
+  const [open, setOpen] = useState(false);
+  const share = useShare({
+    url: props.url,
+    title: props.title,
+    text: props.text,
+    ...(props.onShared !== undefined ? { onShared: props.onShared } : {}),
+  });
+  const label = t(LISTINGS_I18N_KEYS.shareAction);
+  const circle = props.shape === "circle";
+  const notice = useNotice();
+  const copied = share.copied;
+
+  // The toast, and it is the AMPLIFIER of the sentence already standing in
+  // the menu — never the only copy of it. See `notice.ts`.
+  useEffect(() => {
+    if (copied) notice(t(LISTINGS_I18N_KEYS.shareCopied));
+  }, [copied, notice, t]);
+
+  const onNetwork = useCallback(
+    (channel: ShareNetwork): void => {
+      share.report(channel);
+      setOpen(false);
+    },
+    [share]
+  );
+
+  /**
+   * The button itself.
+   *
+   * In the MENU arm it carries no `onClick` of its own: the `Popover` clones
+   * its own click handler onto this child, and a second handler toggling the
+   * same controlled state would open the menu and close it again inside one
+   * gesture — the defect `GateReasonPopover` documents at length, reached
+   * from the other direction.
+   */
+  const trigger = (
+    <Button
+      {...(circle ? { shape: "circle" as const } : {})}
+      className={LISTING_ACTION_CLASS}
+      aria-label={label}
+      data-testid={testId}
+      // WHICH ARM IS ON SCREEN, published rather than inferred. A walker
+      // reading a live phone has no other way to tell a native sheet (which
+      // opens outside the page and leaves no DOM behind) from a menu that
+      // failed to open.
+      data-share-mode={share.native ? "native" : "menu"}
+      data-analytics="none"
+      data-analytics-reason="business action — host app wraps with its own tracked()"
+      icon={<ShareIcon />}
+      {...(props.style !== undefined ? { style: props.style } : {})}
+      {...(share.native ? { onClick: share.shareNatively } : {})}
+    >
+      {circle ? null : (
+        <span className={LISTING_ACTION_LABEL_CLASS}>{label}</span>
+      )}
+    </Button>
+  );
+
+  const sheet = (
+    <>
+      <style href={LISTING_ACTIONS_STYLE_HREF} precedence="default">
+        {actionRowCss()}
+      </style>
+      {trigger}
+    </>
+  );
+
+  // The platform's own sheet: no overlay of ours, nothing to lay out.
+  if (share.native) return sheet;
+
+  const menu = (
+    <Flex vertical gap={spacing[1]} data-testid={`${testId}-menu`}>
+      <Button
+        type="text"
+        className={LISTING_ACTION_CLASS}
+        icon={<LinkIcon />}
+        data-testid={`${testId}-copy`}
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+        onClick={share.copy}
+      >
+        {t(LISTINGS_I18N_KEYS.shareCopy)}
+      </Button>
+
+      {/* THE CONFIRMATION LIVES HERE, and the toast is the amplifier.
+          A toast is transient and can land under a thumb; this sentence
+          stands in the menu the person is looking at. `aria-live` because it
+          appears without anything else changing that a screen reader would
+          otherwise report. */}
+      {share.copied ? (
+        <Typography.Text
+          type="success"
+          aria-live="polite"
+          data-testid={`${testId}-copied`}
+        >
+          {t(LISTINGS_I18N_KEYS.shareCopied)}
+        </Typography.Text>
+      ) : null}
+
+      {/* A clipboard that refused — no permission, an insecure origin, a
+          browser without the API. A person who pressed "copy" and pastes
+          nothing has to be told the press did not work. */}
+      {share.copyFailed ? (
+        <ErrorAlert
+          testId={`${testId}-copy-error`}
+          message={t(LISTINGS_I18N_KEYS.shareCopyFailed)}
+          variant="inline"
+        />
+      ) : null}
+
+      {share.links.map((link) => (
+        <a
+          key={link.channel}
+          href={link.href}
+          target="_blank"
+          rel="noopener noreferrer"
+          className={LISTING_ACTION_CLASS}
+          data-testid={`${testId}-${link.channel}`}
+          data-analytics="none"
+          data-analytics-reason="business action — host app wraps with its own tracked()"
+          onClick={() => {
+            onNetwork(link.channel);
+          }}
+        >
+          {t(NETWORK_LABEL[link.channel])}
+        </a>
+      ))}
+    </Flex>
+  );
+
+  return (
+    <>
+      <style href={LISTING_ACTIONS_STYLE_HREF} precedence="default">
+        {actionRowCss()}
+      </style>
+      {/* eslint-disable-next-line stapel/no-tooltip-in-skin -- see the header: click-only trigger, live anchor, four controls in the overlay rather than an explanation */}
+      <Popover
+        trigger={["click"]}
+        open={open}
+        onOpenChange={setOpen}
+        content={menu}
+        data-testid={`${testId}-popover`}
+      >
+        {trigger}
+      </Popover>
+    </>
+  );
+}

package/src/default/actionRow.ts

@@ -0,0 +1,131 @@
+/**
+ * The geometry of a listing's action row — the heart, the share button, and
+ * the rules that make both of them reachable with a thumb.
+ *
+ * Split out of `<ListingActions>` so `<ShareAction>` can carry the same class
+ * without the two modules importing each other, and so the numbers below are
+ * something a test can READ rather than something a rendered button implies.
+ *
+ * ── Why a class and not an inline style ───────────────────────────────────
+ *
+ * Three of the four rules here cannot be written inline at all: a media query
+ * (the label that disappears on a phone), a descendant selector (the hit area
+ * of whatever element the skin registry substituted for antd's button), and
+ * `:focus-visible`. The fourth — the 44px floor — is written here with them so
+ * that "how big is this control" has ONE answer in this package instead of one
+ * per surface, which is how the SERP heart ended up 32px while the feed
+ * heart was 40 and neither was the number the platform guidelines ask for.
+ *
+ * ── 44 px, and where the number comes from ────────────────────────────────
+ *
+ * `controls["height-phone"]` — the token dictionary's own touch floor, the
+ * same value `SkinTheme` feeds antd as `controlHeight` on a phone (WCAG 2.5.8
+ * and both platform HIGs land on 44 CSS px). It is applied here as a MINIMUM
+ * on every viewport rather than only on a phone: these two controls are small
+ * glyphs pinned to the corner of a photograph, and a 32px circle at the edge
+ * of an image is a miss on a touchscreen laptop as surely as on a phone.
+ */
+import { breakpoints, controls, radii, spacing } from "@stapel/tokens";
+
+/** The class every control in the PAGE cluster carries: the 44px floor. */
+export const LISTING_ACTION_CLASS = "stapel-listing-action";
+/**
+ * The class a CARD's control carries — the same floor, one tier smaller on a
+ * pointer device.
+ *
+ * A card heart is drawn forty to a screen on a desktop grid, where the
+ * reference classified uses a 36px target and a cursor hits it every time;
+ * the same glyph on a phone is a thumb target and goes back to 44. Two tiers
+ * rather than one number, because a 44px circle in the corner of a 267px
+ * photograph is a fifth of the picture's height on a desktop — measured
+ * against the reference (§23), which is why this is not simply
+ * {@link LISTING_ACTION_CLASS}.
+ *
+ * The GLYPH does not change size in either tier; only the box around it does.
+ */
+export const LISTING_CARD_ACTION_CLASS = "stapel-listing-card-action";
+/** The class the cluster's row carries. */
+export const LISTING_ACTIONS_CLASS = "stapel-listing-actions";
+/**
+ * The class that pins the cluster to the trailing TOP corner of the media it
+ * is drawn over.
+ *
+ * Top-trailing is the one corner of a card gallery that is free: the dots own
+ * the bottom centre (`SkinCarousel`) and the "3 of 16" counter owns the
+ * bottom trailing corner (`cardGalleryCss`). Nothing here may move into
+ * either, which is why this is a named constant with a comment rather than
+ * two numbers picked per surface.
+ */
+export const LISTING_ACTIONS_OVERLAY_CLASS = "stapel-listing-actions-over";
+/** The class on the WORD beside a glyph — painted on a desktop, dropped on a
+ * phone, where the same word is still the control's accessible name. */
+export const LISTING_ACTION_LABEL_CLASS = "stapel-listing-action-label";
+/** The `href` the hoisted action-row stylesheet is deduplicated by. */
+export const LISTING_ACTIONS_STYLE_HREF = "stapel-listings-action-row";
+
+/**
+ * The minimum touch target for every control in the cluster, in CSS pixels.
+ *
+ * Exported so a host laying out beside the cluster measures against the same
+ * number — and so `test/shareAction.test.tsx` asserts the rule carries THIS
+ * value rather than a literal that could drift from the token.
+ */
+export const LISTING_ACTION_HIT: number = controls["height-phone"];
+
+/**
+ * A CARD control's minimum target on a pointer device, in CSS pixels.
+ *
+ * The reference classified's own desktop measurement (§23). It is not on the
+ * token scale, and it is not meant to be: the scale carries a control HEIGHT
+ * (32) and a touch FLOOR (44), and this is the third thing — the smallest box
+ * a cursor reliably hits around a 16px glyph. Named, with the measurement,
+ * rather than typed into a stylesheet as `36`.
+ *
+ * On a phone the card control goes back to {@link LISTING_ACTION_HIT}: there
+ * is no such thing as a small touch target.
+ */
+export const LISTING_CARD_ACTION_HIT = 36;
+
+export function actionRowCss(): string {
+  const action = `.${LISTING_ACTION_CLASS}`;
+  const cardAction = `.${LISTING_CARD_ACTION_CLASS}`;
+  const row = `.${LISTING_ACTIONS_CLASS}`;
+  const over = `.${LISTING_ACTIONS_OVERLAY_CLASS}`;
+  const label = `.${LISTING_ACTION_LABEL_CLASS}`;
+  const hit = String(LISTING_ACTION_HIT);
+  const phone = `(max-width:${String(breakpoints.tablet - 1)}px)`;
+  return [
+    // The floor. `min-*` rather than `width`/`height`: a share button with a
+    // word in it is wider than 44px and must stay so, and antd's own
+    // `controlHeight` already reaches the height on a phone — this is the
+    // guarantee for every OTHER viewport and for a host-registered button
+    // that never read the antd token at all.
+    `${action}{min-inline-size:${hit}px;min-block-size:${hit}px;` +
+      `display:inline-flex;align-items:center;justify-content:center}`,
+    // A card's control: one tier smaller where there is a cursor, the same
+    // 44px where there is a thumb. See LISTING_CARD_ACTION_HIT.
+    `${cardAction}{min-inline-size:${String(LISTING_CARD_ACTION_HIT)}px;` +
+      `min-block-size:${String(LISTING_CARD_ACTION_HIT)}px;` +
+      `display:inline-flex;align-items:center;justify-content:center}`,
+    `@media ${phone}{${cardAction}{min-inline-size:${hit}px;min-block-size:${hit}px}}`,
+    // The cluster. `align-items:flex-end` so a blocked heart's reason — the
+    // one thing here that can be two lines — stacks against the same edge
+    // instead of pushing the controls inwards (the arrangement
+    // `<ListingFeedCard>` already ships).
+    `${row}{display:flex;align-items:flex-end;gap:${String(spacing[2])}px}`,
+    // Over a photograph. `z-index:2` puts it above the counter's `1`; the two
+    // never meet anyway (top-trailing against bottom-trailing) and the layer
+    // is stated so a future third overlay has an order to join.
+    `${over}{position:absolute;inset-block-start:${String(spacing[2])}px;` +
+      `inset-inline-end:${String(spacing[2])}px;z-index:2;` +
+      `flex-direction:column;align-items:flex-end;` +
+      `border-radius:${String(radii.full)}px}`,
+    // THE WORD DISAPPEARS ON A PHONE, THE NAME NEVER DOES. Both controls
+    // carry their `aria-label` in every arm, so what a screen reader
+    // announces is identical at 390px and at 1440px; what changes is whether
+    // there is room to paint the word as well. A viewport query rather than a
+    // container one: this is chrome, not a layout that has to fit a track,
+    // and the question really is "is this a phone".
+    `@media ${phone}{${label}{display:none}}`,
+  ].join("");
+}