@stapel/listings-react 0.25.10 → 0.27.0

package/dist/default/ListingDetailPane.d.ts

@@ -1,57 +1,8 @@
-/**
- * `<ListingDetailPane>` — the listing page, and the page a marketplace makes
- * its money on.
- *
- * Five distinct absences, five distinct sentences, and the whole point of the
- * component is that none of them collapses into another:
- *
- *   loading            — we are asking
- *   failed             — we could not ask   (retry, never "nothing here")
- *   not found          — no listing ever had this id
- *   removed            — one did, and it is gone (the AllowAny status probe
- *                        is the only read that can still say so)
- *   withdrawn          — one did, and its owner took it off the shelf: the
- *                        detail 404s while the probe still answers "not
- *                        deleted". NO retry — nothing a retry could change.
- *
- * On top of that, a listing that IS returned may still not be on sale: the
- * detail endpoint has no `published()` filter, so a draft answers 200 to
- * anyone holding the id. The pane says which side of that it is on rather
- * than dressing a draft up as a shop page.
- *
- * ── The page has ONE primary action, and it depends on who is reading ──────
- *
- * For two releases the only control here was "Save to favourites" — the money
- * screen of a marketplace with no way to reach the seller, and the owner's own
- * copy of the page offering to favourite their own listing. So:
- *
- *   a buyer  → `contactSlot` (the container's `@stapel/chat-react`
- *              "message the seller" button), with favouriting beside it as
- *              the secondary it always was;
- *   the owner → Edit and Take down, and no contact button at all — you do not
- *              message yourself.
- *
- * `contactSlot` is a SLOT because conversations belong to another L2 pair and
- * L2 pairs do not import each other. Unfilled it renders `<SlotPlaceholder>`,
- * so an app wired without a chat is a named gap in a dev build rather than a
- * page whose only verb is "save".
- *
- * ── The page has a DESKTOP, when the host says so ──────────────────────────
- *
- * Measured on a live classified deployment at 1440×900: the whole listing
- * page was a ~930px single column hugging the start edge, the price a 22px
- * line UNDER the title and smaller than it, and the right half of the screen
- * empty — while the reference design for this page is two columns: gallery +
- * description + specs on the left, a sticky buy column on the right with the
- * price LARGE at its top, then the actions, then the seller block.
- *
- * `layout="split"` is that design. The HOST states the axis — the same rule
- * 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.
- */
 import type { ReactElement, ReactNode } from "react";
 import type { SignInCta } from "@stapel/core";
+import type { ShareChannel } from "../headless/Share.js";
+import type { ListingActionsConfig } from "./ListingActions.js";
+import type { ListingGalleryLayout } from "./detailGallery.js";
 import type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";
 /** The reading measure of the page body. A detail page is prose plus a spec
  * table; past this it stops being one column and starts being a stripe across
@@ -73,12 +24,30 @@ export declare const DETAIL_SPLIT_MEASURE = "75rem";
  * `1fr` and this is not.
  */
 export declare 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 declare 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).
+ *
+ * The gallery painted a flat `spacing[3]` — 12px on a 390px phone and 12px on
+ * a 1280px desktop — while the page around it had already decided that its
+ * edge is 4px on a phone and 24px on a desktop. Measured on the live listing:
+ * `getComputedStyle(gallery).gap` answered `12px` at both widths, so neither
+ * of the two declared numbers was ever on screen and the tiles sat closer
+ * together than the page edge on a desktop and three times further apart than
+ * it on a phone.
+ *
+ * `--stapel-page-gutter` is a RESPONSIVE token role (`@stapel/tokens`: 4px
+ * phone, 8px tablet, 24px desktop, declared once with its own media arms), and
+ * reading it as a VAR rather than computing a number is the load-bearing half:
+ * a value picked in JS is applied at render, so a window resized between
+ * renders keeps the gutter it was drawn with, where a var reflows. Written
+ * through `cssVar` so a renamed role fails to compile instead of silently
+ * resolving to nothing, with the flat value this grid used before as the
+ * fallback for a host that loads no token stylesheet.
+ */
+export declare const DETAIL_GALLERY_GUTTER: string;
 export interface ListingDetailPaneProps extends ThemeModeProp, CategoryFeaturesProp {
     readonly id: number;
     /** The reader's own uuid, when the host knows it. Enables the owner view —
@@ -147,10 +116,144 @@ export interface ListingDetailPaneProps extends ThemeModeProp, CategoryFeaturesP
     /** Open the composer on this listing — the owner's primary. Absent is a real
      * answer: the button then states that this app has no editing screen. */
     readonly onEdit?: (id: number) => void;
-    /** Extra chrome beside the primary (the seller's profile link, a share
-     * button). Cross-pair navigation is the container's job (spec §6.2 item 5),
-     * so this pair takes nodes rather than routes. */
-    readonly actions?: ReactNode;
+    /**
+     * TWO THINGS UNDER ONE NAME, and the type tells them apart.
+     *
+     *  - a NODE — extra chrome beside the primary (the seller's profile link, a
+     *    control from another pair). What this prop has always been, unchanged,
+     *    and still rendered at the end of the buy box. Cross-pair navigation is
+     *    the container's job (spec §6.2 item 5), so this pair takes nodes
+     *    rather than routes.
+     *  - a CONFIG — `{ share: false }` / `{ favorite: false }`, switching off
+     *    one of the page's own two reader actions.
+     *
+     * A union rather than a second prop, because they are the same question
+     * ("what is in the action row") asked from two sides, and it is
+     * unambiguous at runtime: a plain object that is not a React element was
+     * never a legal `ReactNode` in the first place — React refuses to render
+     * one — so `{ share: false }` cannot be a node that somebody meant.
+     */
+    readonly actions?: ReactNode | ListingActionsConfig;
+    /**
+     * The listing's CANONICAL address, for the share sheet — the route the
+     * container built (`/l/7`, or an absolute URL), not the address bar.
+     *
+     * Absent, sharing falls back to `window.location.href`, which is honest for
+     * a bare mount and wrong for a real app: the address a visitor is standing
+     * on carries the SERP query they arrived from, the page anchor and whatever
+     * tracking parameters came with them, and none of that belongs in a link
+     * somebody sends to a friend. See `useShare`.
+     */
+    readonly shareUrl?: string;
+    /** Analytics: which channel a completed share went through. */
+    readonly onShared?: (channel: ShareChannel) => void;
+    /**
+     * How many people saved this listing, when the host was told by something
+     * else. The listings wire carries `is_favorited` — a per-reader boolean —
+     * and no aggregate at all, so this pair never invents the number and never
+     * draws a zero in place of "nobody counted".
+     */
+    readonly favoriteCount?: number;
+    /**
+     * WHERE THE READER'S TWO ACTIONS SIT.
+     *
+     *  - `"header"` (default) — beside the title, at the trailing edge of the
+     *    heading row, which is where the reference classified puts them and
+     *    where a person looks for them on both a phone and a desktop;
+     *  - `"gallery"` — pinned over the photographs' trailing top corner, for a
+     *    phone-first host that wants them on the picture. The corner is chosen
+     *    rather than free: the dots own the bottom centre of the strip and the
+     *    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;
+     *  - `"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 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
@@ -183,5 +286,10 @@ export interface ListingDetailPaneProps extends ThemeModeProp, CategoryFeaturesP
     readonly headingLevel?: 1 | 2 | 3;
     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";
 export declare function ListingDetailPane(props: ListingDetailPaneProps): ReactElement;
 //# sourceMappingURL=ListingDetailPane.d.ts.map

package/dist/default/ListingDetailPane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ListingDetailPane.d.ts","sourceRoot":"","sources":["../../src/default/ListingDetailPane.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAiBrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAe9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtE;;oBAEoB;AACpB,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;;iCAIiC;AACjC,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,MAAM,WAAW,sBACf,SAAQ,aAAa,EACnB,oBAAoB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;6BAEyB;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACrC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,GAAG,eAAe,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IACjC;6EACyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;sDAEkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAyhB7E"}
+{"version":3,"file":"ListingDetailPane.d.ts","sourceRoot":"","sources":["../../src/default/ListingDetailPane.tsx"],"names":[],"mappings":"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"}