@stapel/listings-react 0.26.0 → 0.28.0

package/src/default/ListingDetailPane.tsx

@@ -49,8 +49,34 @@
  * as CategoryPage's `subcategories`: a decision taken once by the component
  * that knows the viewport it granted, never a media query guessed in a leaf —
  * and the default `"column"` renders exactly what existing hosts already get.
+ *
+ * ── The reader's cluster can be in TWO places, and is ONE thing ────────────
+ *
+ * A phone reads this page over four screens. Past the first, the reference
+ * classified draws a condensed bar — back, the title, and the two verbs — and
+ * a container building one had to mount a `<ListingActions>` of its own,
+ * because `actionsPlacement` took a single value and the pane exposed no
+ * target for the cluster it builds. That second mount is a second
+ * `useFavoriteToggle` on one page: two hearts that agree only after a refetch,
+ * two `aria-pressed` controls, and a second set of test ids kept in step by
+ * hand so the pane's own stayed single.
+ *
+ * `actionsPlacement={["header", "bar"]}` + `renderActionsBar` is the answer,
+ * and the shape is deliberate: the render prop is handed a MOUNT POINT, not
+ * the cluster. `<ListingActions>` is rendered once through a portal and the
+ * portal's container is moved between the two slots as a DOM node, so the
+ * component mounts once, holds one hook, and is literally the same element in
+ * both places (`movableCluster.tsx` has the argument; the test holds the
+ * favourite across the move and compares identity). A render prop handed the
+ * cluster's ELEMENT would have read the same at a call site and mounted twice,
+ * which is the defect with the pair's name on it.
+ *
+ * `onTitleVisible` is the other half: the same container watched the pane's
+ * `<h1>` through its published test id and a `MutationObserver`, for a
+ * boolean the pane already knows. It is an `IntersectionObserver` on the
+ * title, never a scroll listener.
  */
-import { isValidElement } from "react";
+import { isValidElement, useCallback, useEffect, useRef } from "react";
 import type { ReactElement, ReactNode } from "react";
 import { Descriptions, Divider, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
@@ -76,11 +102,18 @@ import { useListingActions } from "../headless/ListingActions.js";
 import { asFeatureDaoList, featureValuesForDisplay } from "../model/features.js";
 import { formatSpecValue } from "../model/featureText.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
-import type { ShareChannel } from "../headless/Share.js";
+import type { ShareChannel, SharePreference } from "../headless/Share.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
 import { ListingActions } from "./ListingActions.js";
 import type { ListingActionsConfig } from "./ListingActions.js";
 import { LISTING_ACTION_CLASS } from "./actionRow.js";
+import {
+  LISTINGS_GALLERY_CLASS,
+  LISTINGS_GALLERY_STYLE_HREF,
+  detailGalleryCss,
+} from "./detailGallery.js";
+import type { ListingGalleryLayout } from "./detailGallery.js";
+import { useMovableCluster } from "./movableCluster.js";
 import { useNotice } from "./notice.js";
 import { ListingSpecColumns, ListingSpecList } from "./ListingSpecList.js";
 import { SignInLink } from "./SignInLink.js";
@@ -113,12 +146,9 @@ export const DETAIL_SPLIT_MEASURE = "75rem";
  */
 export const DETAIL_SPLIT_ASIDE = "380px";
 
-/** 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. */
-export const DETAIL_PHOTO_MIN = "14rem";
+/** Re-exported: the tile floor is declared beside the track it feeds, in
+ * `detailGallery.ts`. */
+export { DETAIL_PHOTO_MIN } from "./detailGallery.js";
 
 /**
  * THE GUTTER BETWEEN TWO PHOTOGRAPHS, and it is the page's own (D418).
@@ -241,6 +271,14 @@ export interface ListingDetailPaneProps
    * somebody sends to a friend. See `useShare`.
    */
   readonly shareUrl?: string;
+  /**
+   * Which arm the share control uses — handed to `<ShareAction prefer>`
+   * through the cluster. Default `"auto"`: the platform sheet where the
+   * primary pointer is coarse, this pair's menu on a mouse. See
+   * `SharePreference` for the measurement that made the pointer part of the
+   * question (§25).
+   */
+  readonly sharePrefer?: SharePreference;
   /** Analytics: which channel a completed share went through. */
   readonly onShared?: (channel: ShareChannel) => void;
   /**
@@ -262,9 +300,96 @@ export interface ListingDetailPaneProps
    *    photo counter owns the bottom trailing corner;
    *  - `"buy-box"` — inside `listings-detail-actions`, beside "message the
    *    seller", which is where the favourite alone used to live. The escape
-   *    hatch for a host whose page was laid out around it.
+   *    hatch for a host whose page was laid out around it;
+   *  - `"bar"` — the condensed top bar the host draws through
+   *    {@link renderActionsBar}. Only meaningful in a LIST beside one of the
+   *    three above, and only with that render prop: it names a second place
+   *    the one cluster may travel to, never a home of its own.
+   *
+   * A LIST is how a host says "both": `["header", "bar"]` keeps the cluster
+   * beside the title and lends it to the bar for as long as the bar is on
+   * screen. Exactly one home placement is honoured — the first non-`"bar"`
+   * entry — because two homes would need two instances, which is the defect
+   * this closes rather than the feature it adds.
+   */
+  readonly actionsPlacement?:
+    | ListingActionsPlacement
+    | readonly ListingActionsPlacement[];
+  /**
+   * THE SAME CLUSTER, IN A SECOND PLACE — a condensed bar, typically.
+   *
+   * Called with the bar's MOUNT POINT, not with a copy of the cluster: return
+   * it wrapped in whatever chrome the bar is (`position: fixed`, a back arrow,
+   * the title), and the pane moves its one `<ListingActions>` into it. Return
+   * `null` while the bar is not on screen and the cluster goes back where it
+   * came from — the same DOM node, the same hooks, an optimistic favourite
+   * still in flight uninterrupted.
+   *
+   * Requires `"bar"` in {@link actionsPlacement}. Pair it with
+   * {@link onTitleVisible} for the usual rule: the bar appears when the title
+   * leaves the fold.
+   *
+   * ```tsx
+   * <ListingDetailPane
+   *   actionsPlacement={["header", "bar"]}
+   *   onTitleVisible={(visible) => { setBarShown(!visible); }}
+   *   renderActionsBar={(cluster) =>
+   *     barShown ? <div className="topbar">{back}{title}{cluster}</div> : null
+   *   }
+   * />
+   * ```
+   *
+   * A container that mounted its own second `<ListingActions>` for this can
+   * delete it: two `useFavoriteToggle` instances on one page, two hearts that
+   * agree only after a refetch, and a second set of test ids to keep the
+   * pane's own single are all what this prop exists to end.
    */
-  readonly actionsPlacement?: "header" | "gallery" | "buy-box";
+  readonly renderActionsBar?: (cluster: ReactNode) => ReactNode;
+  /**
+   * IS THE TITLE STILL IN THE FOLD?
+   *
+   * An `IntersectionObserver` on the pane's own `<h1>` — never a `scroll`
+   * listener, which asks the question on every frame of a page whose job is
+   * scrolling photographs and answers it no better. Called on each crossing
+   * and not on every scroll: `false` when the title leaves, `true` when it
+   * comes back.
+   *
+   * It exists because the chrome a host hangs on this had no way to ask. A
+   * container drawing a condensed bar found the title by the pane's published
+   * `data-testid` and waited for it with a `MutationObserver`, because the
+   * title lands with the listing and not with the first frame — a private
+   * selector and a subscription, for a boolean the pane already knows.
+   *
+   * NOT called at all where the environment has no `IntersectionObserver`:
+   * the honest answer there is "this page cannot tell", and a fabricated
+   * `true` would leave a host's bar wedged open on the arm that has no
+   * scrolling anyway.
+   *
+   * Pass a STABLE function (a `useState` setter, a `useCallback`). The
+   * observer is created once for the title node and reads the latest callback
+   * through a ref, so an inline arrow works and does not re-observe.
+   */
+  readonly onTitleVisible?: (visible: boolean) => void;
+  /**
+   * WHAT SHAPE THE PHOTOGRAPHS ARE IN.
+   *
+   *  - `"grid"` (default) — the element-width grid this pane has always drawn,
+   *    `repeat(auto-fit, minmax(14rem, 1fr))`: three tiles across a desktop
+   *    pane, one across a phone;
+   *  - `"strip"` — a snap-scrolling horizontal strip, one photograph visible
+   *    with the next peeking. On a 390px phone the grid resolves to one
+   *    column, so a listing with three pictures pushes its own title and price
+   *    nearly three screens down — the first thing a person sees after tapping
+   *    a search result is a photograph with nothing beside it.
+   *
+   * The HOST names it, the same rule as {@link layout} and for the same
+   * reason: the side that knows the viewport it granted decides, and no media
+   * query is guessed in a leaf. A live storefront was carrying
+   * `display: flex !important` against this pane's inline `display: grid` to
+   * say exactly this; that declaration is a class now, so even a host wanting
+   * a third shape needs a selector rather than an `!important`.
+   */
+  readonly galleryLayout?: ListingGalleryLayout;
   /**
    * The container's sign-in door, rendered beside the favourite's refusal —
    * the same `SignInCta` seam the three card skins already take. The pane was
@@ -295,9 +420,128 @@ export interface ListingDetailPaneProps
    * Default `3`, byte-compatible for every existing mount.
    */
   readonly headingLevel?: 1 | 2 | 3;
+  /**
+   * WHERE THE BUY COLUMN'S STICKY TOP EDGE IS — the offset of whatever chrome
+   * is pinned above this page (`layout="split"` only; the one-column arm has
+   * no sticky column).
+   *
+   * ```tsx
+   * // the height <PublicShell> publishes, read rather than restated
+   * <ListingDetailPane layout="split" buyTop="var(--stapel-header-height)" />
+   * ```
+   *
+   * The column is `position: sticky; top: 16px` written INLINE, and an inline
+   * declaration is beaten by nothing short of `!important` — so a host with a
+   * pinned header had no way to say "start below it". Measured on the stand
+   * (D456): the storefront's header is sticky and 64px tall, and at any scroll
+   * depth the top of the buy column — the price's own first twenty pixels —
+   * sat UNDER it. Same seam and same argument as `<SearchPage railTop>`, which
+   * this prop is deliberately spelled after.
+   *
+   * A number is pixels; a string is taken as written (a `var()`, a `calc()`,
+   * `"4rem"`). Default `spacing[4]` — 16px, exactly where the column has
+   * always started — so an existing mount is byte-compatible.
+   */
+  readonly buyTop?: number | string;
+  /**
+   * HOW WIDE THE PANE MAY GET — the `max-width` it writes on its own root.
+   *
+   * Default is the constant for the arm on screen: {@link DETAIL_MEASURE}
+   * (60rem) in `"column"`, {@link DETAIL_SPLIT_MEASURE} (75rem) in `"split"`,
+   * so no existing mount changes shape. Anything CSS `max-width` takes is
+   * accepted (`"80rem"`, `1280`, `"100%"`).
+   *
+   * `"none"` removes the cap, and it is the answer for a pane mounted inside
+   * a page frame that already decided the measure. That case is not
+   * hypothetical: measured on the stand at 1440 (D457), the listing page's
+   * content ended at x=1224 with 216px of empty gutter beside it while every
+   * other page of the same site ran to the frame's edge — a second, lower cap
+   * inside a container that already had one. The cap is written INLINE, so
+   * the container could not outrank it without `!important` and reached for
+   * `min-inline-size: 100%` instead (a minimum beats a maximum by the sizing
+   * rules); this prop is that workaround's replacement, and the same seam
+   * `<CategoryPage measure>` already offers.
+   */
+  readonly measure?: number | string;
   readonly footer?: ReactNode;
 }
 
+/**
+ * Where the reader's cluster may sit. Three homes and one loan — see
+ * {@link ListingDetailPaneProps.actionsPlacement}.
+ */
+export type ListingActionsPlacement =
+  | "header"
+  | "gallery"
+  | "buy-box"
+  | "bar";
+
+/** The cluster's HOME: the first entry that is not the borrowed bar. */
+function homePlacement(
+  placement: ListingDetailPaneProps["actionsPlacement"]
+): Exclude<ListingActionsPlacement, "bar"> {
+  if (placement === undefined) return "header";
+  if (typeof placement === "string") {
+    // `"bar"` alone names no home — the cluster still has to live somewhere
+    // while the bar is off screen, and that somewhere is the default.
+    return placement === "bar" ? "header" : placement;
+  }
+  for (const one of placement) {
+    if (one !== "bar") return one;
+  }
+  return "header";
+}
+
+/** Did the host ask for the borrowed placement at all? */
+function wantsBar(
+  placement: ListingDetailPaneProps["actionsPlacement"]
+): boolean {
+  if (placement === undefined) return false;
+  if (typeof placement === "string") return placement === "bar";
+  return placement.includes("bar");
+}
+
+/** Priorities for the two mount points: the bar wins while it is on screen. */
+const CLUSTER_HOME = 0;
+const CLUSTER_BAR = 1;
+
+/**
+ * The pane's own title, watched — see
+ * {@link ListingDetailPaneProps.onTitleVisible}.
+ *
+ * Returns a callback ref for the heading element. The observer is created once
+ * per node and disconnected by React 19's ref cleanup; the host's callback is
+ * read through a ref at call time, so an inline arrow does not re-observe on
+ * every render of a page that re-renders on every query update.
+ */
+function useTitleVisibility(
+  onTitleVisible: ((visible: boolean) => void) | undefined
+): (node: HTMLElement | null) => (() => void) | undefined {
+  const latest = useRef(onTitleVisible);
+  useEffect(() => {
+    latest.current = onTitleVisible;
+  });
+  const wanted = onTitleVisible !== undefined;
+  return useCallback(
+    (node: HTMLElement | null): (() => void) | undefined => {
+      if (node === null || !wanted) return undefined;
+      // No observer, no answer. A fabricated `true` would wedge a host's bar
+      // open on an arm that has no scrolling to close it with.
+      if (typeof IntersectionObserver === "undefined") return undefined;
+      const observer = new IntersectionObserver((entries) => {
+        const entry = entries[entries.length - 1];
+        if (entry === undefined) return;
+        latest.current?.(entry.isIntersecting);
+      });
+      observer.observe(node);
+      return () => {
+        observer.disconnect();
+      };
+    },
+    [wanted]
+  );
+}
+
 /**
  * Which arm of `actions` this is.
  *
@@ -335,7 +579,18 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   // leaves rendering the reason to `<GatedControl>`, which computes its own.
   const favoriteView = useActionGate(bag.favoriteGate);
   const split = props.layout === "split";
-  const placement = props.actionsPlacement ?? "header";
+  const placement = homePlacement(props.actionsPlacement);
+  /* THE SECOND PLACEMENT IS A LOAN, NOT A COPY. Both halves have to be asked
+     for: `"bar"` in the placement list says the cluster may travel, and
+     `renderActionsBar` is the only thing that can put it anywhere. With
+     neither — every existing mount — nothing below changes: one cluster,
+     rendered inline where it always was, no portal and no slot divs. */
+  const galleryLayout: ListingGalleryLayout = props.galleryLayout ?? "grid";
+  const renderBar = props.renderActionsBar;
+  const barred = wantsBar(props.actionsPlacement) && renderBar !== undefined;
+  const movable = useMovableCluster(barred);
+  const moving = barred && movable.portable;
+  const titleRef = useTitleVisibility(props.onTitleVisible);
   // The two arms of `actions` — see `isActionsConfig`.
   const actionsConfig: ListingActionsConfig | undefined = isActionsConfig(
     props.actions
@@ -388,7 +643,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
     <SkinTheme
       surface="base"
       style={{
-        maxWidth: split ? DETAIL_SPLIT_MEASURE : DETAIL_MEASURE,
+        maxWidth: props.measure ?? (split ? DETAIL_SPLIT_MEASURE : DETAIL_MEASURE),
         // See `gutter`: a frame that already placed the page edge does not get
         // a second one stacked inside it.
         padding: props.gutter === "shell" ? 0 : spacing[4],
@@ -566,18 +821,55 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                 {...(listing.title !== undefined && listing.title !== null
                   ? { shareTitle: listing.title }
                   : {})}
+                {...(props.sharePrefer !== undefined
+                  ? { sharePrefer: props.sharePrefer }
+                  : {})}
                 {...(props.onShared !== undefined ? { onShared: props.onShared } : {})}
               />
             );
 
+            /* What the PAGE draws where the cluster lives. With the bar in
+               play that is a slot and not the cluster itself: the cluster is
+               rendered once into `clusterLayer` below and travels between the
+               two slots as a DOM node, so it mounts once, holds one
+               `useFavoriteToggle`, and keeps its element identity across the
+               move. Without it, the cluster is drawn inline exactly as it has
+               always been. */
+            const homeActions = moving
+              ? movable.slot(CLUSTER_HOME, placement)
+              : readerActions;
+
+            /* The one instance, plus the host's bar around the slot that may
+               borrow it. Rendered at the end of the page's own flow: the
+               portal has no position of its own (its content is wherever the
+               winning slot is), and a bar is `position: fixed` chrome whose
+               place in the document order is not its place on the screen. */
+            const clusterLayer =
+              !moving || renderBar === undefined ? null : (
+                <>
+                  {movable.render(readerActions)}
+                  {/* NOT a slot with a silent absence: `renderBar` is the only
+                      thing that makes `moving` true, so this arm is
+                      unreachable without one and the host's own `null` (the
+                      bar off screen) is the answer that sends the cluster
+                      home. There is no hole to place a `<SlotPlaceholder>` in
+                      — the cluster is at its primary placement instead. */}
+                  {renderBar(movable.slot(CLUSTER_BAR, "bar"))}
+                </>
+              );
+
             /* Element-width tiles: the grid decides how many fit, the
                photos fill them. */
             const gallery = (
               <div
                 data-testid="listings-detail-gallery"
+                className={LISTINGS_GALLERY_CLASS}
+                // The layout is a CLASS and an attribute, not an inline
+                // `display`: a host with a shape neither arm offers can then
+                // write CSS for it at its own breakpoints without `!important`
+                // over a pair's own geometry. See `detailGallery.ts`.
+                data-gallery-layout={galleryLayout}
                 style={{
-                  display: "grid",
-                  gridTemplateColumns: `repeat(auto-fit, minmax(${DETAIL_PHOTO_MIN}, 1fr))`,
                   // The page's own edge, per breakpoint — see
                   // `DETAIL_GALLERY_GUTTER` (D418).
                   gap: DETAIL_GALLERY_GUTTER,
@@ -587,6 +879,9 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                   position: "relative",
                 }}
               >
+                <style href={LISTINGS_GALLERY_STYLE_HREF} precedence="default">
+                  {detailGalleryCss()}
+                </style>
                 {bag.images.length === 0 ? (
                   <ListingPhoto
                     imageRef={undefined}
@@ -604,7 +899,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     />
                   ))
                 )}
-                {placement === "gallery" ? readerActions : null}
+                {placement === "gallery" ? homeActions : null}
               </div>
             );
 
@@ -621,12 +916,13 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                 <Flex align="flex-start" justify="space-between" gap={spacing[3]}>
                   <Typography.Title
                     level={props.headingLevel ?? 3}
+                    ref={titleRef}
                     data-testid="listings-detail-title"
                     style={{ minWidth: 0, flex: "1 1 auto" }}
                   >
                     {listing.title ?? ""}
                   </Typography.Title>
-                  {placement === "header" ? readerActions : null}
+                  {placement === "header" ? homeActions : null}
                 </Flex>
 
                 {/* The `show_at_title` projection, formatted from the stored
@@ -741,7 +1037,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                 {/* The reader's two actions live in the cluster now (see
                     `actionsPlacement`); the buy box keeps them only when a
                     host asks for the layout this page used to have. */}
-                {placement === "buy-box" ? readerActions : null}
+                {placement === "buy-box" ? homeActions : null}
 
                 {actionsNode}
               </Flex>
@@ -888,6 +1184,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                   {meta}
                   {asideAfterActions ? null : aside}
                   {props.footer}
+                  {clusterLayer}
                 </>
               );
             }
@@ -928,7 +1225,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     data-testid="listings-detail-buy-column"
                     style={{
                       position: "sticky",
-                      top: spacing[4],
+                      top: props.buyTop ?? spacing[4],
                       alignSelf: "start",
                     }}
                   >
@@ -938,6 +1235,7 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     {aside}
                   </Flex>
                 </div>
+                {clusterLayer}
               </>
             );
           },

package/src/default/MyListingsPane.tsx

@@ -23,8 +23,11 @@
  *    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
+ *    So the takedowns are the fourth tab. It was counted from its own read
+ *    while the counter had three integers; since stapel-listings 0.22.4 the
+ *    counter has four and the badge is the SERVER's, so the tab appears and
+ *    is right without the takedown page having landed — 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.
@@ -571,10 +574,11 @@ 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, 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).
+                  // read lower than the rows underneath it, and the fourth
+                  // tab's number degrades to its own rows on a server older
+                  // than 0.22.4 (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={tab === "removed" ? "warning" : "secondary"}

package/src/default/ShareAction.tsx

@@ -10,16 +10,22 @@
  *
  * ── 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.
+ * On a device driven with a THUMB 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.
+ * Everywhere else 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 reading that decides is the primary POINTER and not `navigator.share`
+ * alone: desktop Chrome on macOS has the API, so the capability question sent
+ * every desktop share to the OS sheet and left this menu unreachable on the
+ * platform it was written for (§25). {@link ShareActionProps.prefer} is where
+ * a host overrules the reading in either direction.
  *
  * ── The menu is a Popover, and that is an exception with an argument ──────
  *
@@ -60,7 +66,11 @@ 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 type {
+  ShareChannel,
+  ShareNetwork,
+  SharePreference,
+} from "../headless/Share.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import {
   LISTING_ACTIONS_STYLE_HREF,
@@ -104,6 +114,21 @@ export interface ShareActionProps {
    * for it.
    */
   readonly shape?: "default" | "circle";
+  /**
+   * WHICH ARM THIS SURFACE WANTS — see {@link SharePreference}.
+   *
+   * Default `"auto"`: the platform sheet where the primary pointer is coarse
+   * AND `navigator.share` exists, this pair's menu everywhere else. The
+   * default changed in this release, and it changed because of a measurement
+   * (§25): desktop Chrome on macOS reports `navigator.share`, so a pair that
+   * asked only the capability opened the OS sheet on the desktop and the
+   * copy-link menu — three networks and a clipboard row, built for exactly
+   * that platform — could not be reached there at all.
+   *
+   * `"native"` restores the capability-only behaviour by name; `"menu"` pins
+   * this pair's menu on every device.
+   */
+  readonly prefer?: SharePreference;
   readonly style?: CSSProperties;
 }
 
@@ -115,6 +140,7 @@ export function ShareAction(props: ShareActionProps): ReactElement {
     url: props.url,
     title: props.title,
     text: props.text,
+    ...(props.prefer !== undefined ? { prefer: props.prefer } : {}),
     ...(props.onShared !== undefined ? { onShared: props.onShared } : {}),
   });
   const label = t(LISTINGS_I18N_KEYS.shareAction);

package/src/default/actionRow.ts

@@ -86,13 +86,62 @@ export const LISTING_ACTION_HIT: number = controls["height-phone"];
  */
 export const LISTING_CARD_ACTION_HIT = 36;
 
+/**
+ * HOW MANY TIMES THE HIT-TARGET CLASS IS REPEATED IN ITS OWN SELECTOR — and
+ * why a repeat rather than a number typed once (D450).
+ *
+ * Measured on the live listing page: the heart and the share glyph were
+ * **32 × 44**, not 44 × 44. The block axis survived and the inline one did
+ * not, because antd's circle shape ships
+ *
+ *   `:where(…).ant-btn.ant-btn-circle.ant-btn{min-width:var(--ant-control-height)}`
+ *
+ * — three classes, specificity (0,3,0), against this sheet's single class
+ * (0,1,0). `:where()` adds nothing, and a media query adds nothing either, so
+ * the only thing that decides is the class count: antd's 32 won and there was
+ * no viewport at which it did not.
+ *
+ * A repeated class is the one way to outrank it without `!important`. Four
+ * repeats — (0,4,0) — clear antd's three with one to spare, and the selector
+ * still matches exactly the same element, so nothing about WHAT the rule
+ * applies to changes. `!important` was refused deliberately: a host that
+ * genuinely wants a different target must be able to say so with a selector,
+ * and this sheet's whole argument (see `movableCluster.tsx`) is that a pair's
+ * geometry should never force one on somebody else.
+ */
+export const LISTING_ACTION_SPECIFICITY = 4;
+
+/** A class name repeated {@link LISTING_ACTION_SPECIFICITY} times — the
+ * selector that beats antd's circle. */
+function outranking(className: string): string {
+  return `.${className}`.repeat(LISTING_ACTION_SPECIFICITY);
+}
+
+/**
+ * The floor, in BOTH spellings of the same axis.
+ *
+ * A browser cascades `min-inline-size` and `min-width` together and keeps the
+ * winner, so in a browser the logical pair alone would be enough once the
+ * selector outranks antd's. The physical pair is written beside it because
+ * the declaration being beaten is spelled physically, and an engine that does
+ * NOT merge the two names (jsdom, where this rule is asserted) would leave
+ * antd's `min-width:32px` standing beside our `min-inline-size:44px` and call
+ * that a pass. Two spellings of one number, and the number has one source.
+ */
+function floor(size: number): string {
+  const px = `${String(size)}px`;
+  return (
+    `min-inline-size:${px};min-block-size:${px};` +
+    `min-width:${px};min-height:${px}`
+  );
+}
+
 export function actionRowCss(): string {
-  const action = `.${LISTING_ACTION_CLASS}`;
-  const cardAction = `.${LISTING_CARD_ACTION_CLASS}`;
+  const action = outranking(LISTING_ACTION_CLASS);
+  const cardAction = outranking(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
@@ -100,14 +149,13 @@ export function actionRowCss(): string {
     // `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;` +
+    `${action}{${floor(LISTING_ACTION_HIT)};` +
       `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;` +
+    `${cardAction}{${floor(LISTING_CARD_ACTION_HIT)};` +
       `display:inline-flex;align-items:center;justify-content:center}`,
-    `@media ${phone}{${cardAction}{min-inline-size:${hit}px;min-block-size:${hit}px}}`,
+    `@media ${phone}{${cardAction}{${floor(LISTING_ACTION_HIT)}}}`,
     // 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