@stapel/listings-react 0.25.10 → 0.27.0

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("");
+}

package/src/default/cardGallery.ts

@@ -46,9 +46,12 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { PointerEvent as ReactPointerEvent, RefObject } from "react";
+import { fontSize, radii, spacing } from "@stapel/tokens";
 
 /** The class the gallery's own box carries — see {@link cardGalleryCss}. */
 export const CARD_GALLERY_CLASS = "stapel-listing-gallery";
+/** The class the "3 of 16" pill carries — see {@link cardGalleryCss}. */
+export const CARD_GALLERY_COUNTER_CLASS = "stapel-listing-gallery-count";
 /** The `href` the hoisted gallery stylesheet is deduplicated by. */
 export const CARD_GALLERY_STYLE_HREF = "stapel-listings-card-gallery";
 
@@ -338,7 +341,35 @@ export function useCardGallery(count: number): CardGallery {
  */
 export function cardGalleryCss(): string {
   const box = `.${CARD_GALLERY_CLASS}`;
+  const counter = `.${CARD_GALLERY_COUNTER_CLASS}`;
   return [
+    // The counter is placed against this box, so the box has to be the
+    // containing block. Nothing else about the gallery changes: a `relative`
+    // with no offsets moves no pixel of what is already in it.
+    `${box}{position:relative}`,
+    // "3 of 16", bottom-TRAILING corner — the dots own the bottom centre
+    // (`SkinCarousel`: `inset-inline:0; justify-content:center`) and two
+    // indicators fighting for one spot is worse than neither.
+    //
+    // `pointer-events:none` is load-bearing rather than tidy: this box owns
+    // the hover-scrub and the swipe, and an element that swallowed a pointer
+    // would make one corner of every card's photograph dead to both gestures.
+    //
+    // A FIXED scrim and white text, not a theme role, and this is the one
+    // place in the package where that is the right answer: the pill sits on
+    // an arbitrary PHOTOGRAPH, which is neither light nor dark, so a value
+    // that followed the page's theme would be unreadable on half the photos
+    // in either one.
+    `${counter}{position:absolute;inset-block-end:${String(spacing[2])}px;` +
+      `inset-inline-end:${String(spacing[2])}px;z-index:1;pointer-events:none;` +
+      `padding:${String(spacing[1] / 2)}px ${String(spacing[2])}px;` +
+      `border-radius:${String(radii.full)}px;` +
+      `background:rgba(0,0,0,0.55);color:#fff;` +
+      `font-size:${String(fontSize.xs.fontSize)}px;` +
+      `line-height:${String(fontSize.xs.lineHeight)}px;` +
+      // A counter whose digits change width makes the pill twitch on every
+      // swipe.
+      `font-variant-numeric:tabular-nums}`,
     // THE VERTICAL AXIS IS THE BROWSER'S, and is not negotiable: a card is a
     // small box in a long feed, and the one unacceptable outcome of a gallery
     // gesture is a page that will not scroll. `pan-y` says so at the platform

package/src/default/detailGallery.ts

@@ -0,0 +1,97 @@
+/**
+ * HOW THE LISTING PAGE LAYS OUT ITS PHOTOGRAPHS — and why the answer is a
+ * class and a prop rather than an inline `display`.
+ *
+ * ── The defect a container was carrying ───────────────────────────────────
+ *
+ * The gallery is an element-width grid (`repeat(auto-fit, minmax(14rem,
+ * 1fr))`), which on a 390px phone resolves to ONE column: a listing with three
+ * pictures pushes its own title and price nearly three screens down, and the
+ * first thing a person sees after tapping a search result is a photograph with
+ * nothing beside it. A phone lays photographs out as a snap-scrolling STRIP —
+ * one visible with the next peeking, title and price directly under it.
+ *
+ * That is layout, and layout is the container's to decide. But the pane wrote
+ * `display: grid` INLINE, and an inline declaration is beaten by nothing that
+ * is not `!important` — so a live storefront carried
+ * `[data-testid="listings-detail-gallery"] { display: flex !important }`
+ * against a pair's own geometry, named by a test id, to say a thing the pair
+ * offered no way to say (a client storefront's own stylesheet, §2).
+ *
+ * ── The seam ──────────────────────────────────────────────────────────────
+ *
+ * Two halves, and both matter:
+ *
+ *  1. `<ListingDetailPane galleryLayout>` — the pane ships BOTH layouts and
+ *     the host names one, exactly as it already names `layout="split"` and
+ *     `gutter`. The host is the side that knows the viewport it granted;
+ *     a media query guessed in a leaf is the thing this package does not do.
+ *  2. `display` and the track are no longer inline. They live on this
+ *     stylesheet, at one class plus one attribute, so a host that wants
+ *     something neither arm offers can still write CSS for it at its own
+ *     breakpoints — and needs no `!important` to be heard, only a selector of
+ *     its own (`[data-testid="listings-detail-gallery"][data-gallery-layout]`
+ *     ties; add any third condition and it wins).
+ *
+ * What stays inline is what nobody overrides and what a stylesheet would make
+ * worse: the `gap` (the page's own responsive gutter token, D418 — a var, so
+ * a resize reflows it) and `position: relative`, which is the containing block
+ * the `actionsPlacement="gallery"` overlay is pinned to.
+ */
+/**
+ * The narrowest a gallery tile may get before the grid drops a column. A
+ * measure rather than a pixel: the tiles then fill whatever the ELEMENT is,
+ * which is §83's geometry rule — one photo per row on a phone, three on a
+ * desktop pane, and no `width: 320` that is near-full-bleed on one and a
+ * postage stamp on the other.
+ *
+ * Declared here rather than in `<ListingDetailPane>` because this is the file
+ * that writes the track it feeds; the pane re-exports it, so the public name
+ * is unchanged.
+ */
+export const DETAIL_PHOTO_MIN = "14rem";
+
+/** Which shape the photographs take. See the file header. */
+export type ListingGalleryLayout = "grid" | "strip";
+
+/** The class the gallery box carries. */
+export const LISTINGS_GALLERY_CLASS = "stapel-listings-detail-gallery";
+
+/** The `href` the hoisted gallery stylesheet is deduplicated by. */
+export const LISTINGS_GALLERY_STYLE_HREF = "stapel-listings-detail-gallery";
+
+/**
+ * How much of the strip's width ONE photograph takes.
+ *
+ * Not 100: the remaining sliver of the next picture is the only thing on a
+ * phone that says the strip scrolls at all. Exported so a host laying out
+ * beside it measures against the same number instead of guessing it back out
+ * of a screenshot.
+ */
+export const LISTINGS_GALLERY_STRIP_BASIS = "86%";
+
+/**
+ * The gallery's layout rules, for the hoisted `<style>`.
+ *
+ * The strip's child rule (`> *`) is the reason this is a stylesheet and not
+ * two more inline properties: an inline style cannot reach a child, and the
+ * flex basis is what makes the strip a strip rather than a row of squeezed
+ * photographs.
+ */
+export function detailGalleryCss(): string {
+  return `
+.${LISTINGS_GALLERY_CLASS}[data-gallery-layout="grid"] {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(${DETAIL_PHOTO_MIN}, 1fr));
+}
+.${LISTINGS_GALLERY_CLASS}[data-gallery-layout="strip"] {
+  display: flex;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+}
+.${LISTINGS_GALLERY_CLASS}[data-gallery-layout="strip"] > * {
+  flex: 0 0 ${LISTINGS_GALLERY_STRIP_BASIS};
+  scroll-snap-align: start;
+}
+`.trim();
+}

package/src/default/favorite.tsx

@@ -35,6 +35,8 @@ import { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
 import { HeartIcon } from "./icons.js";
+import { useNotice } from "./notice.js";
+import { LISTING_ACTIONS_STYLE_HREF, actionRowCss } from "./actionRow.js";
 
 export interface FavoriteHeartProps {
   readonly listingId: number;
@@ -83,6 +85,31 @@ export interface FavoriteHeartProps {
    * its reason, which is all a surface with no sign-in route can offer.
    */
   readonly signIn?: SignInCta;
+  /**
+   * The hit-target class this surface wants — `LISTING_CARD_ACTION_CLASS` on
+   * a card (36px with a cursor, 44px with a thumb),
+   * `LISTING_ACTION_CLASS` on the listing page (44px everywhere).
+   *
+   * A CLASS rather than a size prop: the tiers are a media query, and a
+   * component that took a number would have to be told the viewport — which
+   * is the thing a leaf must never ask. See `actionRow.ts`.
+   */
+  readonly className?: string;
+  /**
+   * SAY THE OUTCOME OUT LOUD — a short toast on each successful press.
+   *
+   * Off by default and ON for the listing page: one heart on a screen the
+   * person came to act on earns a sentence, forty hearts on a grid do not.
+   * The icon fill remains the state in both cases; this is the acknowledgement
+   * that the press was received, which is the half a small glyph pinned to
+   * the corner of a photograph cannot carry on its own.
+   *
+   * It is raised on the GESTURE, from the predicted next state, for the same
+   * reason `useFavoriteToggle` draws that state optimistically: the toast has
+   * to arrive with the press. A write that then fails rolls the icon back and
+   * states the failure through the heart's own `ErrorAlert`.
+   */
+  readonly announce?: boolean;
   readonly style?: CSSProperties;
 }
 
@@ -134,6 +161,7 @@ export interface FavoriteHeartProps {
  */
 export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   const t = useT();
+  const notice = useNotice();
   const { token } = antdTheme.useToken();
   const favorite = useFavoriteToggle(props.listingId, props.favorited);
   const label = t(
@@ -154,6 +182,22 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   // place a blocked reason becomes words in this fleet.
   const gate = useActionGate(favorite.gate);
   const reason = gate.reason;
+  // The press, plus the sentence the surface asked for. The next state is the
+  // one the icon is about to draw, so the toast and the fill say the same
+  // thing at the same moment — see `announce`.
+  const announce = props.announce === true;
+  const press = (): void => {
+    const next = !favorite.favorited;
+    favorite.toggle();
+    if (!announce || !favorite.gate.available) return;
+    notice(
+      t(
+        next
+          ? LISTINGS_I18N_KEYS.favoriteAdded
+          : LISTINGS_I18N_KEYS.favoriteRemoved
+      )
+    );
+  };
   // D431. A blocked gate plus a door the surface handed in: the press is not
   // refused, it is ROUTED — through the door, keeping whatever `?next=` the
   // container put in the href. With no door there is nothing better for the
@@ -175,9 +219,10 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
         ...doorPress,
         ...(door?.href !== undefined ? {} : { "aria-pressed": favorite.favorited }),
       }
-    : { "aria-pressed": favorite.favorited, onClick: favorite.toggle };
+    : { "aria-pressed": favorite.favorited, onClick: press };
   // A failed save, stated where the heart is. The rollback already put the
   // icon back; this says why it went back.
+  // (see `press` above for the toast that rides the successful half)
   const failure = (
     <ErrorAlert
       testId={`${props.testId}-error`}
@@ -185,8 +230,20 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
       variant="inline"
     />
   );
+  // The hit-target rules the surfaces address by class. Hoisted here rather
+  // than by each card, because the heart is what carries the class and a
+  // stylesheet that arrived only on the surfaces that remembered it is a
+  // 32px target on the one that forgot.
+  const sheet = (
+    <style href={LISTING_ACTIONS_STYLE_HREF} precedence="default">
+      {actionRowCss()}
+    </style>
+  );
+
   if (props.blockedReason === "popover" && reason !== undefined) {
     return (
+      <>
+      {sheet}
       <GateReasonPopover
         reason={reason}
         cta={props.signIn}
@@ -201,6 +258,9 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
             // control, and the disclosure stays as the hint beside it.
             {...(opensDoor ? {} : { "aria-disabled": true })}
             {...bind}
+            {...(props.className !== undefined
+              ? { className: props.className }
+              : {})}
             aria-label={label}
             data-testid={props.testId}
             data-favorited={String(favorite.favorited)}
@@ -212,9 +272,12 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
           />
         )}
       </GateReasonPopover>
+      </>
     );
   }
   return (
+    <>
+    {sheet}
     <GatedControl
       gate={favorite.gate}
       testId={props.gateTestId ?? `${props.testId}-gate`}
@@ -233,6 +296,9 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
             shape="circle"
             // See `<ListingCard>`: the substrate's binding, spread whole.
             {...bind}
+            {...(props.className !== undefined
+              ? { className: props.className }
+              : {})}
             aria-label={label}
             data-testid={props.testId}
             data-favorited={String(favorite.favorited)}
@@ -245,5 +311,6 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
         </>
       )}
     </GatedControl>
+    </>
   );
 }

package/src/default/icons.tsx

@@ -50,6 +50,66 @@ export function HeartIcon(props: HeartIconProps): ReactElement {
   );
 }
 
+/**
+ * The share glyph — three nodes and two edges, the platform-neutral shape
+ * both Android and the web draw for "send this somewhere else".
+ *
+ * `aria-hidden`, like the heart: the control it sits in carries the verb as
+ * its accessible name in every arm, including the phone arm where the word
+ * itself is not painted, and a glyph announced beside its own label reads the
+ * action twice.
+ *
+ * Deliberately not the iOS "box with an arrow": that shape means "share" to
+ * an iPhone user and "upload" or "export" to everybody else, and this control
+ * is drawn on a browser, not inside an app the platform styled.
+ */
+export function ShareIcon(): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-hidden="true"
+    >
+      <circle cx="18" cy="5" r="3" />
+      <circle cx="6" cy="12" r="3" />
+      <circle cx="18" cy="19" r="3" />
+      <path d="M8.6 10.5 15.4 6.6" />
+      <path d="M8.6 13.5 15.4 17.4" />
+    </svg>
+  );
+}
+
+/**
+ * A chain link — the copy row's glyph, and the one thing on the menu that is
+ * not a network's own brand.
+ */
+export function LinkIcon(): ReactElement {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-hidden="true"
+    >
+      <path d="M10 13a5 5 0 0 0 7.5.6l3-3a5 5 0 0 0-7-7l-1.7 1.7" />
+      <path d="M14 11a5 5 0 0 0-7.5-.6l-3 3a5 5 0 0 0 7 7l1.7-1.7" />
+    </svg>
+  );
+}
+
 /**
  * Which way the asking price moved — an arrow, and a NAME for it.
  *

package/src/default/index.ts

@@ -71,8 +71,22 @@ export {
   DETAIL_SPLIT_MEASURE,
   DETAIL_SPLIT_ASIDE,
   DETAIL_PHOTO_MIN,
+  DETAIL_GALLERY_GUTTER,
 } from "./ListingDetailPane.js";
-export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
+export type {
+  ListingDetailPaneProps,
+  ListingActionsPlacement,
+} from "./ListingDetailPane.js";
+// The gallery's two shapes, its class and the stylesheet behind them — a host
+// that wants a third writes CSS against these rather than `!important` over an
+// inline `display`.
+export {
+  LISTINGS_GALLERY_CLASS,
+  LISTINGS_GALLERY_STYLE_HREF,
+  LISTINGS_GALLERY_STRIP_BASIS,
+  detailGalleryCss,
+} from "./detailGallery.js";
+export type { ListingGalleryLayout } from "./detailGallery.js";
 export {
   ListingComposerPage,
   COMPOSER_DETAILS_PLACEMENT,
@@ -126,6 +140,28 @@ export {
   useCardGallery,
 } from "./cardGallery.js";
 export type { CardGallery } from "./cardGallery.js";
+// ── the reader's two actions: save it, or send it to somebody ───────────────
+export { ListingActions } from "./ListingActions.js";
+export type {
+  ListingActionsConfig,
+  ListingActionsProps,
+} from "./ListingActions.js";
+export { ShareAction } from "./ShareAction.js";
+export type { ShareActionProps } from "./ShareAction.js";
+export {
+  LISTING_ACTIONS_CLASS,
+  LISTING_ACTIONS_OVERLAY_CLASS,
+  LISTING_ACTIONS_STYLE_HREF,
+  LISTING_ACTION_CLASS,
+  LISTING_ACTION_HIT,
+  LISTING_ACTION_LABEL_CLASS,
+  LISTING_CARD_ACTION_CLASS,
+  LISTING_CARD_ACTION_HIT,
+  actionRowCss,
+} from "./actionRow.js";
+export { NOTICE_SECONDS, useNotice } from "./notice.js";
+export type { Notice } from "./notice.js";
+
 export { SignInLink } from "./SignInLink.js";
 export type { SignInLinkProps } from "./SignInLink.js";
 export type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";

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