@stapel/listings-react 0.29.1 → 0.30.0

package/src/default/ListingRelated.tsx

@@ -0,0 +1,154 @@
+/**
+ * "FIND MORE" — the two strips a listing page ends with, and why they are two.
+ *
+ * The reference classified draws them as separate sections with separate
+ * promises (§16 comparison 4): "more options like this one", which is the
+ * category and the listing's main axes, and "other listings from this seller",
+ * which is one person's shelf. A buyer reading the first is still shopping;
+ * a buyer reading the second has decided who they are buying from. Collapsing
+ * them into one "related" rail answers neither question.
+ *
+ * ── WHERE THE ROWS COME FROM, and why not from here ───────────────────────
+ *
+ * Both lists are SEARCH results, and this pair does not read search: the query
+ * is `category=<slug>` plus the main axis filters for the first, and
+ * `owner=<uuid>` for the second, and building either means knowing a search
+ * module's parameter names and a category's slug — neither of which a listings
+ * pair has (the detail wire carries `category_id`, a number, and no slug).
+ *
+ * So the seam is two-sided and the host picks its side:
+ *
+ *  - `similar` / `fromSeller` — the ROWS, already fetched. The pane draws
+ *    this component with them, which is the whole of what a host needs on a
+ *    storefront that already has a search client;
+ *  - `renderSimilar` / `renderFromSeller` — the SLOT, handed everything the
+ *    pane knows to build a query with ({@link ListingRelatedContext}). For a
+ *    host whose "more like this" is not a strip of cards at all — the
+ *    reference's own first mechanism is a set of catalogue LINKS, not
+ *    listings.
+ *
+ * Neither is drawn empty. A heading over nothing is worse than no heading: it
+ * reads as a section that failed to load.
+ */
+import type { ReactElement, ReactNode } from "react";
+import { Flex, Typography } from "antd";
+import { useT } from "@stapel/core";
+import type { LinkComponent } from "@stapel/core";
+import { spacing } from "@stapel/tokens";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import type {
+  ListingCard as ListingCardData,
+  ListingFeatureView,
+} from "../api/types.js";
+import { ListingFeedCard } from "./ListingFeedCard.js";
+
+/** The class the horizontal strip carries. */
+export const RELATED_STRIP_CLASS = "stapel-listings-related";
+/** The `href` the hoisted strip stylesheet is deduplicated by. */
+export const RELATED_STYLE_HREF = "stapel-listings-related";
+
+/**
+ * How much of the page width ONE card takes in the strip.
+ *
+ * A `min()` rather than a percentage: on a 390px phone the reference shows
+ * roughly one and a half cards, so the next one peeks and the strip says it
+ * scrolls; on a desktop a card that kept scaling with the page would be a
+ * 700px tile of a 200px photograph.
+ */
+export const RELATED_CARD_BASIS = "min(46%, 220px)";
+
+/**
+ * What the pane knows about this listing, for a host building the queries.
+ *
+ * `categoryId` is the wire's own value and it is a STRING there — the detail
+ * serializer types it `string | null`, and this contract does not quietly
+ * reinterpret it.
+ */
+export interface ListingRelatedContext {
+  readonly listingId: number;
+  /** The listing's category, as the wire carries it. */
+  readonly categoryId: string | undefined;
+  /** The seller — the `owner=` filter's value. */
+  readonly ownerKey: string | undefined;
+  /**
+   * The listing's MAIN AXES, as the category itself projected them: the
+   * `show_at_title` subset, which is the same set a card's title line prints
+   * and the nearest thing to "what makes two of these alike".
+   */
+  readonly axes: readonly ListingFeatureView[];
+}
+
+/** The strip's rule an inline style cannot reach: the cards' flex basis. */
+export function relatedStripCss(): string {
+  return (
+    `.${RELATED_STRIP_CLASS}{display:flex;overflow-x:auto;` +
+      `gap:${String(spacing[3])}px;scroll-snap-type:x proximity}` +
+    `.${RELATED_STRIP_CLASS}>*{flex:0 0 ${RELATED_CARD_BASIS};scroll-snap-align:start}`
+  );
+}
+
+export interface ListingRelatedStripProps {
+  /** The section's caption. */
+  readonly heading: string;
+  readonly items: readonly ListingCardData[];
+  /** Where "show all" goes — the search this strip is a sample of. Absent,
+   * there is no link: a strip of three with nowhere to go is honest, and an
+   * inert "show all" is not. */
+  readonly showAllHref?: string;
+  /** Where one card goes. Absent, the cards are inert — which is what a
+   * host mounting this inside its own link wrapper wants. */
+  readonly listingHref?: (id: number) => string;
+  readonly linkComponent?: LinkComponent;
+  readonly testId: string;
+}
+
+/** One "find more" section: a caption, an optional link out, and a scrolling
+ * row of the pair's own feed tiles. */
+export function ListingRelatedStrip(
+  props: ListingRelatedStripProps
+): ReactElement | null {
+  const t = useT();
+  const { items, listingHref } = props;
+  if (items.length === 0) return null;
+  const Link = props.linkComponent;
+  const showAll =
+    props.showAllHref === undefined ? null : Link !== undefined ? (
+      <Link href={props.showAllHref} data-testid={`${props.testId}-all`}>
+        {t(LISTINGS_I18N_KEYS.detailShowAll)}
+      </Link>
+    ) : (
+      <Typography.Link href={props.showAllHref} data-testid={`${props.testId}-all`}>
+        {t(LISTINGS_I18N_KEYS.detailShowAll)}
+      </Typography.Link>
+    );
+
+  return (
+    <Flex vertical gap={spacing[2]} data-testid={props.testId}>
+      <style href={RELATED_STYLE_HREF} precedence="default">
+        {relatedStripCss()}
+      </style>
+      <Flex align="baseline" justify="space-between" gap={spacing[3]}>
+        <Typography.Title level={5} style={{ margin: 0 }}>
+          {props.heading}
+        </Typography.Title>
+        {showAll}
+      </Flex>
+      <div className={RELATED_STRIP_CLASS}>
+        {items.map((row) => {
+          const href = listingHref?.(row.id);
+          const open: ReactNode =
+            href === undefined ? (
+              <ListingFeedCard listing={row} />
+            ) : (
+              <ListingFeedCard
+                listing={row}
+                href={href}
+                {...(Link !== undefined ? { linkComponent: Link } : {})}
+              />
+            );
+          return <div key={row.id}>{open}</div>;
+        })}
+      </div>
+    </Flex>
+  );
+}

package/src/default/ListingSpecList.tsx

@@ -32,6 +32,7 @@
  * digits grouped by the reader's locale. `model/featureText.ts` says where
  * the unit comes from and why there is no `unit` key to read it from.
  */
+import { useState } from "react";
 import type { CSSProperties, ReactElement } from "react";
 import { Typography, theme as antdTheme } from "antd";
 import { SkinTheme } from "@stapel/tokens-antd/skin";
@@ -46,6 +47,7 @@ import {
   isValueVerified,
 } from "@stapel/attributes-react";
 import type { FeatureDef, FeatureValueDto } from "@stapel/attributes-react";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { formatSpecValue } from "../model/featureText.js";
 
 /** The class one spec row carries. */
@@ -85,9 +87,34 @@ export interface ListingSpecListProps {
   /** The surface's own test id, so a split page holding two columns of these
    * does not hand a test two elements under one name. */
   readonly testId?: string;
+  /**
+   * HOW MANY ROWS STAND BEFORE THE FOLD. Default: all of them.
+   *
+   * This is a PRESENTATION limit and nothing else — it hides no field from
+   * anybody, because the control under the list opens the rest in place and
+   * every row is in the accessibility tree once it is open. The reference
+   * classified folds at about eighteen and calls the control "all
+   * characteristics"; the argument is the same one the description has, that
+   * a forty-row list under a photograph on a 390px phone is four screens
+   * between the price and the seller.
+   *
+   * It is a PROP and not a default, because the fold is a decision about a
+   * VIEWPORT and this package does not read viewports (see the pane's
+   * `layout` / `galleryLayout`): a desktop split column with two columns of
+   * rows wants none of it.
+   *
+   * The stated limit is honoured only when it actually saves something: a
+   * list of eleven with a limit of ten draws all eleven rather than a fold
+   * that hides one row behind a button as tall as the row.
+   */
+  readonly limit?: number;
   readonly style?: CSSProperties;
 }
 
+/** How many rows a fold has to hide before it is worth one. See
+ * {@link ListingSpecListProps.limit}. */
+export const SPEC_FOLD_MIN_HIDDEN = 2;
+
 /**
  * A withheld value's row: what the system OBSERVED, and nothing more — the
  * same three states `@stapel/attributes-react` prints, said with its own
@@ -104,10 +131,22 @@ export function ListingSpecList(props: ListingSpecListProps): ReactElement {
   const { locale } = useI18n();
   const { token } = antdTheme.useToken();
 
+  const [open, setOpen] = useState(false);
+
   // A `header` is a section caption in a FORM, not a value: it has none, and
   // a spec table that printed one would print "not specified" under it.
   const rows = props.features.filter((feature) => featureType(feature) !== "header");
 
+  /* THE FOLD, and it folds nothing it cannot save two rows by folding. The
+     limit is counted over the rows that are actually DRAWN, not over the
+     features handed in — a category whose declaration ends in three form
+     headers would otherwise fold a list that is already short. */
+  const limit = props.limit ?? Number.POSITIVE_INFINITY;
+  const folded =
+    !open && rows.length - limit >= SPEC_FOLD_MIN_HIDDEN
+      ? rows.slice(0, limit)
+      : rows;
+
   return (
     <SkinTheme surface="bare">
       <style href={SPEC_STYLE_HREF} precedence="default">
@@ -124,7 +163,7 @@ export function ListingSpecList(props: ListingSpecListProps): ReactElement {
           ...props.style,
         }}
       >
-        {rows.map((feature) => {
+        {folded.map((feature) => {
           const dto = props.values[feature.slug];
           const redacted = isRedactedValue(dto);
           const text = redacted
@@ -152,6 +191,25 @@ export function ListingSpecList(props: ListingSpecListProps): ReactElement {
             </p>
           );
         })}
+        {/* `aria-expanded` rather than a second sentence: the control IS the
+            state, and a person using a screen reader is told the list opened
+            without the list announcing itself. It disappears once open —
+            there is no "show less", because a reader who opened forty rows
+            scrolls past them and does not scroll back up to close them. */}
+        {folded.length === rows.length ? null : (
+          <Typography.Link
+            role="button"
+            aria-expanded={false}
+            data-testid={`${props.testId ?? "listings-spec-list"}-show-all`}
+            data-analytics="none"
+            data-analytics-reason="a look, not an outcome — unfolding a list changes no record"
+            onClick={() => {
+              setOpen(true);
+            }}
+          >
+            {t(LISTINGS_I18N_KEYS.detailShowAll)}
+          </Typography.Link>
+        )}
       </div>
     </SkinTheme>
   );
@@ -165,6 +223,11 @@ export function ListingSpecList(props: ListingSpecListProps): ReactElement {
  * The cut is here rather than inside the list because a CSS `columns` rule
  * would break a wrapped paragraph across the column boundary, which is
  * exactly the defect the paragraph shape was adopted to avoid.
+ *
+ * `limit` is accepted (one props type) and deliberately NOT forwarded: a fold
+ * applied to each half would hide the same count twice and leave two "show
+ * all" controls that open different halves of one list. The two-column arm is
+ * the wide screen, which is the arm the fold exists to spare.
  */
 export function ListingSpecColumns(props: ListingSpecListProps): ReactElement {
   const half = Math.ceil(props.features.length / 2);

package/src/default/condensedBar.ts

@@ -0,0 +1,74 @@
+/**
+ * THE CONDENSED BAR — what a phone reads at the top of a listing page once
+ * the title has scrolled away.
+ *
+ * ── Why the pane draws it, when it already lends the cluster out ───────────
+ *
+ * `renderActionsBar` hands a host the MOUNT POINT and lets it build the bar.
+ * That is the right seam for a container with chrome of its own, and it is
+ * also four things every container then writes identically: a fixed strip at
+ * the top of the viewport, a back control, the listing's title on one line,
+ * and the rule that the bar is on screen exactly while the title is not.
+ * Measured against the reference classified (§24/§25/§29), which shows the
+ * same four from about 160px of scroll on every listing it has.
+ *
+ * So `actionsPlacement={["header", "condensed-top"]}` is the pane drawing it,
+ * with the SAME travelling cluster underneath — one `useFavoriteToggle`, one
+ * `aria-pressed` heart, one share control, moved as a DOM node into the bar's
+ * slot and moved back when the bar goes (`movableCluster.tsx` has the whole
+ * argument). A host that wants a different bar keeps `renderActionsBar`, and
+ * where both are asked for the host's own render prop wins: a pair's default
+ * never overrules a container that said something specific.
+ *
+ * ── The threshold is the TITLE, not a pixel count ─────────────────────────
+ *
+ * The reference's "~160px" is a fact about its own header height, not a
+ * number this pane could honour — the same 160px is mid-gallery on one
+ * storefront and past the price on another. The pane already watches its own
+ * `<h1>` through an `IntersectionObserver` for `onTitleVisible`; the bar
+ * appears when that says the title left the fold, which is what the reference
+ * number approximates and what a person actually reads: the bar carries the
+ * title precisely because the title is no longer on screen.
+ *
+ * ── The geometry is a stylesheet, for two reasons ─────────────────────────
+ *
+ * The ellipsis needs three declarations on the title element and the bar needs
+ * a `position: fixed` a host may want to move under its own header. Written as
+ * a class, a container retunes either with a selector instead of `!important`
+ * over an inline style — the rule `detailGallery.ts` was created to establish.
+ */
+import { cssVar, fontSize, spacing } from "@stapel/tokens";
+
+/** The class the fixed bar carries. */
+export const CONDENSED_BAR_CLASS = "stapel-listings-condensed-bar";
+/** The class the bar's one-line title carries. */
+export const CONDENSED_TITLE_CLASS = "stapel-listings-condensed-title";
+/** The `href` the hoisted bar stylesheet is deduplicated by. */
+export const CONDENSED_BAR_STYLE_HREF = "stapel-listings-condensed-bar";
+
+/**
+ * The bar's rules.
+ *
+ * The colours are token ROLES read as vars rather than resolved numbers: the
+ * bar is painted over whatever the page is scrolling, so it needs an opaque
+ * ground, and a ground picked in JS at render keeps the theme it was drawn
+ * with when the reader switches themes. `z-index: 20` is above a page's own
+ * content and deliberately below the range a modal layer uses.
+ */
+export function condensedBarCss(): string {
+  return [
+    `.${CONDENSED_BAR_CLASS}{position:fixed;inset-block-start:0;inset-inline:0;` +
+      `z-index:20;display:flex;align-items:center;` +
+      `gap:${String(spacing[2])}px;` +
+      `padding:${String(spacing[2])}px ${String(spacing[3])}px;` +
+      `background:${cssVar("surface-raised")};` +
+      `border-block-end:1px solid ${cssVar("border")}}`,
+    // One line, and the end of a long title is the part a reader can spare.
+    // `min-inline-size:0` is what lets it shrink inside the flex row at all —
+    // without it a long title pushes the two verbs off the screen.
+    `.${CONDENSED_TITLE_CLASS}{flex:1 1 auto;min-inline-size:0;` +
+      `overflow:hidden;white-space:nowrap;text-overflow:ellipsis;` +
+      `font-size:${String(fontSize.sm.fontSize)}px;` +
+      `line-height:${String(fontSize.sm.lineHeight)}px}`,
+  ].join("");
+}

package/src/default/detailGallery.ts

@@ -37,7 +37,30 @@
  * 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.
+ *
+ * ── WHERE THE STRIP IS, and why a tap could not answer it ─────────────────
+ *
+ * The strip arm is a native scroll container: a finger moves it, a fling
+ * settles it on a snap point, and neither of those is an event this package
+ * fires. So the page carried a strip that scrolled correctly and a "1 of 7"
+ * that did not move — measured on the reference walk (§20b: `scrollLeft`
+ * driven a full slide, the indicator still reading the first photograph).
+ * Anything keyed off a TAP is the wrong instrument here, because the gesture
+ * that changes the photograph is not a tap.
+ *
+ * {@link useGalleryPosition} is the answer, and it is the strip's own
+ * `scroll` event throttled to one measurement per animation frame — the same
+ * shape `SkinCarousel` already uses for the card's dots, written here because
+ * the detail gallery is this package's own element and mounts no carousel.
+ * `scrollend` is deliberately NOT the trigger: Safari has no such event, and
+ * an indicator that only settles is an indicator that lies for the length of
+ * a fling. The index is read from live rectangles rather than from
+ * `scrollLeft / slideWidth`, for the reason `nearestSlideIndex` gives: the
+ * arithmetic version has to know the gap, the peek and the writing direction.
  */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { fontSize, radii, spacing } from "@stapel/tokens";
+
 /**
  * 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,
@@ -60,6 +83,21 @@ 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";
 
+/** The class the strip's "3 of 16" pill carries. */
+export const LISTINGS_GALLERY_COUNTER_CLASS = "stapel-listings-detail-count";
+
+/**
+ * The class on the box that HOLDS the strip and its counter.
+ *
+ * A frame rather than the gallery itself, and the reason is mechanical: in the
+ * strip arm the gallery element IS the scroll container, and an absolutely
+ * positioned child of a scroller is laid out against its padding box — it
+ * scrolls away with the third photograph. It also cannot be a child of the
+ * strip at all, because `> *` makes every child a slide. So the counter is a
+ * sibling of the strip inside a box that does not scroll.
+ */
+export const LISTINGS_GALLERY_FRAME_CLASS = "stapel-listings-detail-gallery-frame";
+
 /**
  * How much of the strip's width ONE photograph takes.
  *
@@ -70,6 +108,91 @@ export const LISTINGS_GALLERY_STYLE_HREF = "stapel-listings-detail-gallery";
  */
 export const LISTINGS_GALLERY_STRIP_BASIS = "86%";
 
+/**
+ * The index of the child whose leading edge is nearest the box's.
+ *
+ * Exported because it is the whole claim of {@link useGalleryPosition} and a
+ * test can put rectangles in front of it without a layout engine.
+ */
+export function nearestPhotoIndex(box: HTMLElement): number {
+  const origin = box.getBoundingClientRect().left;
+  let best = 0;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (let i = 0; i < box.children.length; i += 1) {
+    const child = box.children.item(i);
+    if (child === null) continue;
+    const distance = Math.abs(child.getBoundingClientRect().left - origin);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = i;
+    }
+  }
+  return best;
+}
+
+/** What the gallery box is handed back — see {@link useGalleryPosition}. */
+export interface GalleryPosition {
+  /** The photograph on screen, 0-based. */
+  readonly active: number;
+  /** Attach to the scrolling box. */
+  readonly ref: (node: HTMLElement | null) => (() => void) | undefined;
+}
+
+/**
+ * WHICH PHOTOGRAPH THE STRIP IS SHOWING — read off the strip itself.
+ *
+ * `enabled` is false for the grid arm and for a single photograph: a grid does
+ * not scroll horizontally and a lone picture has no position, so neither pays
+ * for a listener. The ref then attaches nothing at all.
+ *
+ * The measurement is throttled to one per animation frame, because a momentum
+ * scroll fires dozens of `scroll` events per frame and each measurement is a
+ * layout flush. The state write is guarded on a CHANGE, so a scroll across one
+ * photograph costs one render rather than sixty.
+ */
+export function useGalleryPosition(enabled: boolean): GalleryPosition {
+  const [active, setActive] = useState(0);
+  const frame = useRef<number | null>(null);
+  // Reset when the arm goes away, so a host toggling `galleryLayout` does not
+  // keep a stale index for a grid nobody can scroll back.
+  useEffect(() => {
+    if (!enabled) setActive(0);
+  }, [enabled]);
+  const ref = useCallback(
+    (node: HTMLElement | null): (() => void) | undefined => {
+      if (node === null || !enabled) return undefined;
+      const read = (): void => {
+        frame.current = null;
+        setActive(nearestPhotoIndex(node));
+      };
+      const onScroll = (): void => {
+        if (frame.current !== null) return;
+        // No rAF (an old jsdom, a server-side shim): measure straight away.
+        // A throttle that cannot be scheduled is not a reason to stop
+        // reporting where the strip is.
+        if (typeof requestAnimationFrame !== "function") {
+          read();
+          return;
+        }
+        frame.current = requestAnimationFrame(read);
+      };
+      // A strip can mount already scrolled (a restored position), so the
+      // indicator opens truthful rather than at 1.
+      read();
+      node.addEventListener("scroll", onScroll, { passive: true });
+      return () => {
+        node.removeEventListener("scroll", onScroll);
+        if (frame.current !== null && typeof cancelAnimationFrame === "function") {
+          cancelAnimationFrame(frame.current);
+        }
+        frame.current = null;
+      };
+    },
+    [enabled]
+  );
+  return { active, ref };
+}
+
 /**
  * The gallery's layout rules, for the hoisted `<style>`.
  *
@@ -93,5 +216,23 @@ export function detailGalleryCss(): string {
   flex: 0 0 ${LISTINGS_GALLERY_STRIP_BASIS};
   scroll-snap-align: start;
 }
+.${LISTINGS_GALLERY_FRAME_CLASS} {
+  position: relative;
+  min-inline-size: 0;
+}
+.${LISTINGS_GALLERY_COUNTER_CLASS} {
+  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;
+  font-variant-numeric: tabular-nums;
+}
 `.trim();
 }

package/src/default/detailRhythm.ts

@@ -0,0 +1,78 @@
+/**
+ * ONE GAP BETWEEN THE LISTING PAGE'S BLOCKS, AND THE PANE IS THE ONE WHO SAYS
+ * IT.
+ *
+ * ── What was on screen ────────────────────────────────────────────────────
+ *
+ * `<ListingDetailPane>` stacks its blocks in a `<Flex vertical gap>` and
+ * declares 16px (12px in the buy column). Measured on the stand by the
+ * tidiness probe at 1440 and 390, the gaps INSIDE that flex were 111.05,
+ * 53.59, 42.39, 29 and 27 pixels. Five distances, none of them 16, none of
+ * them chosen by anybody.
+ *
+ * The cause is not the gap. It is that a flex `gap` governs only the space a
+ * container puts BETWEEN its children, and half the children here are antd
+ * components carrying outer margins of their own:
+ *
+ *   `<Divider>`          24px above and 24px below, from antd's own sheet, so
+ *                        one horizontal rule inside a 16px column costs 40 +
+ *                        40;
+ *   `<Typography.Title>` a margin-block-start proportional to its level, which
+ *                        is right for prose in a document flow and is a second
+ *                        opinion inside a container that already spaces its
+ *                        children;
+ *   `<Typography.Paragraph>` a bottom margin of about one line.
+ *
+ * A margin and a gap ADD. So the page's rhythm was the sum of two systems,
+ * and reading either one of them told you nothing about what was drawn.
+ *
+ * ── The rule ──────────────────────────────────────────────────────────────
+ *
+ * `margin-block: 0` on every direct child of the pane's block columns —
+ * the same three-line answer `@stapel/categories-react`'s `blockRhythm.ts`
+ * gives for a catalogue page, and deliberately spelled the same way: a block's
+ * own outer margin is a second opinion about a distance the container already
+ * decided.
+ *
+ * It is a SHEET and not an inline style for the reason every other rule in
+ * this package is: it addresses CHILDREN this component renders but does not
+ * own, and an inline style cannot reach one.
+ *
+ * ── The divider keeps a spacing, because it is not a block ────────────────
+ *
+ * A horizontal rule is a SECTION BREAK: it needs more air than the space
+ * between two blocks, or it reads as another row in the stack. So it is not
+ * zeroed with the rest — it gets {@link DETAIL_RULE_CLASS}, one token step on
+ * each side, which lands the break at `gap + step` and makes the number a
+ * decision instead of whatever antd's 24 happened to sum to. The class beats
+ * the reset on specificity (`.col > .rule` over `.col > *`) without an
+ * `!important`, and a host can out-specify it with one more condition.
+ */
+import { spacing } from "@stapel/tokens";
+
+/** The class the pane's block columns carry. */
+export const DETAIL_RHYTHM_CLASS = "stapel-listings-detail-column";
+
+/** The class the pane's horizontal rule carries. */
+export const DETAIL_RULE_CLASS = "stapel-listings-detail-rule";
+
+/** The `href` the hoisted rhythm sheet is deduplicated by. */
+export const DETAIL_RHYTHM_STYLE_HREF = "stapel-listings-detail-rhythm";
+
+/**
+ * ONE TOKEN STEP of extra air on each side of the section rule — see the file
+ * header. Exported so a test reads the decision rather than a literal, and so
+ * a container laying out beside the rule measures against the same number.
+ */
+export const DETAIL_RULE_SPACE: number = spacing[2];
+
+/** The rhythm's two rules. */
+export function detailRhythmCss(): string {
+  const column = `.${DETAIL_RHYTHM_CLASS}`;
+  return [
+    // A block's own outer margin is a second opinion about the same distance.
+    `${column}>*{margin-block:0}`,
+    // …except the section rule, which is a break and not a block.
+    `${column}>.${DETAIL_RULE_CLASS}{margin-block:${String(DETAIL_RULE_SPACE)}px}`,
+  ].join("");
+}

package/src/default/icons.tsx

@@ -141,3 +141,35 @@ export function PriceTrendIcon(props: {
     </svg>
   );
 }
+
+/**
+ * The condensed bar's back arrow.
+ *
+ * `aria-hidden`, like the heart and the share glyph: the control around it
+ * carries "Back" as its accessible name, and a glyph announced beside its own
+ * label reads the action twice.
+ *
+ * Drawn with the logical writing direction in mind only as far as a library
+ * honestly can: the shape points at the INLINE START, and a right-to-left host
+ * flips it with one `transform` against this package's own class rather than
+ * getting a mirrored copy nobody can name.
+ */
+export function BackIcon(): 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="M19 12H5" />
+      <path d="M12 19l-7-7 7-7" />
+    </svg>
+  );
+}