@stapel/listings-react 0.26.0 → 0.28.0

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/index.ts

@@ -73,7 +73,20 @@ export {
   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,
@@ -142,6 +155,7 @@ export {
   LISTING_ACTION_CLASS,
   LISTING_ACTION_HIT,
   LISTING_ACTION_LABEL_CLASS,
+  LISTING_ACTION_SPECIFICITY,
   LISTING_CARD_ACTION_CLASS,
   LISTING_CARD_ACTION_HIT,
   actionRowCss,

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

package/src/headless/MyListings.tsx

@@ -49,13 +49,23 @@ import { useMandateGate } from "./useMandateGate.js";
  * `blockedRows` is fetched beside them, off the same route, narrowed to
  * whatever `MY_LISTINGS_UNTABBED_STATUSES` derives.
  *
- * That second read is also the fourth tab's COUNT (D407). `my/counters` has
- * three integers and no fourth, so the removed tab is counted from the rows it
- * holds — which is honest exactly because that read is unpaged and runs
- * whichever tab is open. The one thing it cannot describe is a page cap: a
- * seller with more takedowns than one page of `my/listings` would see the page
- * count and not the total, and there is no counter on the wire to check it
- * against (see `MyListingsBag.tabCounts`).
+ * That second read used to be the fourth tab's COUNT as well (D407):
+ * `my/counters` had three integers and no fourth, so the removed tab was
+ * counted from the rows it holds — honest, because that read is unpaged and
+ * runs whichever tab is open, and blind to exactly one thing: a page cap. A
+ * seller with more takedowns than one page of `my/listings` saw the page count
+ * and not the total, and there was no counter on the wire to check it against.
+ *
+ * **stapel-listings 0.22.4 answers it**: `MyCountersResponse.blocked`, required
+ * beside the other three, over the same owner scope and the same grouping. So
+ * the tab's number is the SERVER's now and the unpaged read is what it always
+ * was underneath — the removed tab's ROWS. The two consequences are both
+ * visible: the tab appears from the counter (a beat earlier, and without the
+ * seller's whole takedown page having to land first), and a seller with more
+ * takedowns than fit on a page is told how many there are rather than how many
+ * arrived. A deployment on a server older than 0.22.4 sends no `blocked` at
+ * all, and then the rows are the count again — degraded to the previous
+ * answer, never to a `0` (see `MyListingsBag.tabCounts`).
  */
 
 export interface MyListingsBag {
@@ -66,10 +76,16 @@ export interface MyListingsBag {
    * The server's three always; the removed one only where there is something
    * in it or the person asked for it by address. An empty "Taken down" tab is
    * a scare, and the seller it would scare is the one it has nothing to tell.
+   *
+   * "Something in it" is `counters.blocked` (stapel-listings 0.22.4) and no
+   * longer the unpaged takedown page: the two reads settle independently, and
+   * the one that decides whether a tab strip has three tabs or four should be
+   * the one that answers in three integers rather than the one that answers in
+   * a page of listings.
    */
   readonly tabs: readonly MyListingsTab[];
   setTab(tab: MyListingsTab): void;
-  /** The three real counts, as the server reports them. */
+  /** The four real counts, as the server reports them. */
   readonly counters: LoadState<MyCounters>;
   /**
    * The number to DRAW on each tab — the server's counter, raised to what is
@@ -89,8 +105,13 @@ export interface MyListingsBag {
    *
    * The second half: a takedown was in no tab and therefore in no number, so
    * a cabinet holding one read "Active 0 · Drafts 0 · Archived 0" over it.
-   * `removed` is counted from `blockedRows` — there is no server counter to
-   * read, and the rows are the only evidence on the wire.
+   * `removed` was counted from `blockedRows`, because there was no server
+   * counter to read and the rows were the only evidence on the wire. There is
+   * one now — `MyCountersResponse.blocked`, stapel-listings 0.22.4 — and it is
+   * what the fourth tab draws, under the same floor as the other three: the
+   * open tab's number is never below the rows on screen. `blockedRows` stays
+   * the FALLBACK for a deployment whose server predates the field, which is a
+   * count that is right up to a page and never a `0` over a visible row.
    */
   readonly tabCounts: LoadState<Readonly<Record<MyListingsTab, number>>>;
   /** The rows for the current tab — {@link MyListingsBag.blockedRows} while
@@ -206,8 +227,17 @@ export function useMyListings(
   // The takedown count, when it is known. Not a `0` while the read is in
   // flight: the tab strip is drawn off this number and a tab that appeared a
   // beat after the page settled would move the three beside it.
-  const blockedCount =
+  //
+  // The SERVER's integer first (stapel-listings 0.22.4), the unpaged page's
+  // length only where a deployment's backend predates it. `counters.data` is
+  // typed with `blocked` required, so the runtime check is the honest one and
+  // not a type-driven one: an older server answers 200 with three keys, and a
+  // `?? 0` there would print "Taken down 0" over a row the seller can see.
+  const rowsBlockedCount =
     blockedRows.status === "ready" ? blockedRows.data.length : undefined;
+  const serverBlockedCount =
+    typeof counters.data?.blocked === "number" ? counters.data.blocked : undefined;
+  const blockedCount = serverBlockedCount ?? rowsBlockedCount;
 
   // Paging belongs to the tab's own keyset read. The takedowns are fetched
   // unpaged on purpose, so the removed tab has nowhere to go and says so.
@@ -229,13 +259,23 @@ export function useMyListings(
             one === tab ? Math.max(server[one], visible) : server[one],
           ])
         ) as Readonly<Record<MyListingsCountedTab, number>>),
-        [MY_LISTINGS_REMOVED_TAB]: blockedCount ?? 0,
+        // The fourth tab takes the same floor as the other three: the server's
+        // number, raised to what is on screen while this tab is the open one.
+        // The counter and the unpaged page are two reads of one set and either
+        // may be the staler — a badge under its own rows is not a count.
+        [MY_LISTINGS_REMOVED_TAB]:
+          tab === MY_LISTINGS_REMOVED_TAB
+            ? Math.max(blockedCount ?? 0, visible)
+            : (blockedCount ?? 0),
       });
     }, [counters.status, counters.error, counters.data, rows, tab, blockedCount]);
 
   // The removed tab is drawn where it has something to say — or where the
   // address named it, so `?tab=removed` opens a real (if empty) tab rather
   // than an activeKey pointing at nothing.
+  //
+  // "Something to say" is the COUNTER since 0.22.4, so the tab arrives with
+  // `my/counters` rather than waiting for a page of takedowns to come back.
   const tabs: readonly MyListingsTab[] =
     removed || (blockedCount ?? 0) > 0 ? MY_LISTINGS_TABS : MY_LISTINGS_COUNTED_TABS;
 

package/src/headless/Share.tsx

@@ -17,6 +17,15 @@
  * menu with "copy the link" and the three networks a Russian-speaking
  * marketplace actually gets traffic from.
  *
+ * ── …AND "HAS A SHEET" IS NOT "SHOULD USE THE SHEET" (§25) ───────────────
+ *
+ * `navigator.share` is true on desktop Chrome on macOS. Measured on the stand:
+ * every share on the storefront opened the OS sheet and the copy-link menu —
+ * three networks and a clipboard row, built for exactly that platform — was
+ * unreachable there. So the decision takes a second reading, the primary
+ * POINTER, and {@link UseShareOptions.prefer} lets a surface state the answer
+ * outright. See {@link SharePreference}.
+ *
  * `native` is resolved in an EFFECT rather than during render, for the reason
  * `cardGallery.ts`'s `useFinePointer` gives at length: a server render has no
  * `navigator`, and a first client render that disagreed with it is a
@@ -134,6 +143,70 @@ export function hasNativeShare(): boolean {
   return typeof navigator.share === "function";
 }
 
+/**
+ * The media query that asks "is this a thumb" — the second half of the arm
+ * decision (§25).
+ *
+ * `(pointer: coarse)` describes the PRIMARY input device, which is exactly the
+ * question: a phone and a tablet match, a mouse and a trackpad do not, and a
+ * touchscreen laptop being driven with its trackpad reports the trackpad.
+ */
+export const SHARE_COARSE_MEDIA = "(pointer: coarse)";
+
+/** Does the primary pointer look like a finger? `false` wherever the question
+ * cannot be asked — a server, an engine without `matchMedia` — because the
+ * fallback arm is the one that draws something. */
+export function hasCoarsePointer(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  try {
+    return window.matchMedia(SHARE_COARSE_MEDIA).matches;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * WHICH ARM A SURFACE WANTS, and why `navigator.share` alone was the wrong
+ * question.
+ *
+ * The capability probe is true on desktop Chrome on macOS — measured on the
+ * stand (§25), where every share on the storefront opened the OS sheet and the
+ * copy-link menu was therefore unreachable on the platform it was BUILT for.
+ * "Has a share sheet" and "is a device whose share sheet is the better answer"
+ * turned out to be two questions, and the pair was only asking the first.
+ *
+ *   `"auto"`   (default) the platform sheet only where the primary pointer is
+ *              COARSE and the API exists; a mouse gets the menu, with its
+ *              copy-link row and its three networks.
+ *   `"menu"`   always this pair's menu, whatever the device offers. For a
+ *              host whose desktop and mobile web are one build and which
+ *              wants one answer.
+ *   `"native"` the platform sheet wherever the API exists, pointer ignored —
+ *              the behaviour every version before this one had, kept
+ *              reachable by name rather than deleted.
+ *
+ * In all three, a missing `navigator.share` is the menu: an arm that cannot
+ * open is not an arm.
+ */
+export type SharePreference = "auto" | "menu" | "native";
+
+/**
+ * Resolve the arm from the preference and what the device actually answered.
+ *
+ * Pure, and separate from the hook, so the decision is a thing a test reads
+ * rather than a thing a rendered `data-share-mode` implies.
+ */
+export function preferNativeShare(
+  prefer: SharePreference,
+  capability: { readonly native: boolean; readonly coarse: boolean }
+): boolean {
+  if (prefer === "menu") return false;
+  if (!capability.native) return false;
+  return prefer === "native" || capability.coarse;
+}
+
 export interface UseShareOptions {
   /** The canonical address, absolute or a path. Absent: the address bar,
    * which is the honest answer only for a host with no route seam. */
@@ -146,13 +219,24 @@ export interface UseShareOptions {
    * through; `"native"` never says which app, because the sheet does not
    * tell the page. */
   readonly onShared?: ((channel: ShareChannel) => void) | undefined;
+  /**
+   * Which arm this surface wants — see {@link SharePreference}. Default
+   * `"auto"`: the platform sheet on a coarse pointer, this pair's menu on a
+   * mouse, the menu wherever `navigator.share` is missing.
+   */
+  readonly prefer?: SharePreference | undefined;
 }
 
 export interface ShareBag {
   /** The absolute address every arm shares. `undefined` only on a server. */
   readonly url: string | undefined;
-  /** Does this device have the platform's own sheet? Settles in an effect —
-   * see the file header. */
+  /**
+   * IS THE PLATFORM SHEET THE ARM ON SCREEN — the resolved answer, not the
+   * raw capability. `prefer` and the primary pointer are both in it (see
+   * {@link SharePreference}); `hasNativeShare()` is the capability alone, for
+   * a caller that wants to ask that question itself. Settles in an effect —
+   * see the file header.
+   */
   readonly native: boolean;
   /** The three networks' links, already encoded. */
   readonly links: readonly ShareLink[];
@@ -182,15 +266,24 @@ export const SHARE_COPIED_MS = 2400;
 
 export function useShare(options: UseShareOptions = {}): ShareBag {
   const { url: given, title, text, onShared } = options;
+  const prefer = options.prefer ?? "auto";
   const [native, setNative] = useState(false);
   const [copied, setCopied] = useState(false);
   const [copyFailed, setCopyFailed] = useState(false);
 
   // See the header: resolved in an effect so a server render and the
-  // hydration pass that must agree with it draw the same arm.
+  // hydration pass that must agree with it draw the same arm. Both halves of
+  // the question are asked in the SAME effect — the capability and the
+  // pointer — so there is never a frame in which one has landed and the
+  // other has not and the button changes arm twice.
   useEffect(() => {
-    setNative(hasNativeShare());
-  }, []);
+    setNative(
+      preferNativeShare(prefer, {
+        native: hasNativeShare(),
+        coarse: hasCoarsePointer(),
+      })
+    );
+  }, [prefer]);
 
   const url = useMemo(() => resolveShareUrl(given), [given]);
   const links = useMemo(

package/src/index.ts

@@ -163,7 +163,9 @@ export {
   retainKnownFeatureValues,
 } from "./model/draft.js";
 export type {
+  DraftPatchOptions,
   EmptyDraftOptions,
+  ListingDraftField,
   ListingDraftValues,
   ListingLocation,
 } from "./model/draft.js";
@@ -184,6 +186,7 @@ export { featureUnit, formatSpecValue } from "./model/featureText.js";
 export {
   badgePresentation,
   badgeValueText,
+  captionName,
   cardBadgeText,
   cardBadgeTexts,
   hasCardBadgeContract,
@@ -316,10 +319,13 @@ export type {
   UseFavoritesOptions,
 } from "./headless/Favorites.js";
 export {
+  SHARE_COARSE_MEDIA,
   SHARE_COPIED_MS,
   SHARE_NETWORKS,
   Share,
+  hasCoarsePointer,
   hasNativeShare,
+  preferNativeShare,
   resolveShareUrl,
   shareLinks,
   useShare,
@@ -329,6 +335,7 @@ export type {
   ShareChannel,
   ShareLink,
   ShareNetwork,
+  SharePreference,
   ShareTarget,
   UseShareOptions,
 } from "./headless/Share.js";

package/src/model/cardBadges.ts

@@ -227,12 +227,41 @@ function isTrue(raw: unknown): boolean {
  */
 export type CardBadgeStyle = "badge" | "line";
 
+/**
+ * A CAPTION AS THIS PAIR WILL PUNCTUATE IT — the catalogue's own trailing
+ * colon stripped (D455).
+ *
+ * Measured on a live feed, translated: one card in twenty-four read
+ * "HONOR · **Model:: 90** · 256 GB". The catalogue row for that leaf spells
+ * the feature's name "Model:" — with the colon IN the name — and presents it
+ * `name_value`, while the neighbouring listing's row for the same slug spells
+ * it "Model" and presents it `value`. So the content is inconsistent and only
+ * one half of that is ours; what is ours is that {@link caption} then adds a
+ * second colon to a name that already ended in one.
+ *
+ * Punctuation between a caption and its answer is the SURFACE's decision (see
+ * the module header) — which means it is not the catalogue's, and a name that
+ * arrives carrying its own is a name with a separator baked into it. It is
+ * taken off here, once, so both styles are unaffected by which of the two
+ * spellings a row happens to use: the chip draws "Model 90" and the line
+ * "Model: 90" either way.
+ *
+ * Only a TRAILING colon, and only the colon: a name is otherwise printed
+ * exactly as the catalogue wrote it. "Model: year:" is not a shape anybody
+ * sends, and a rule that chewed punctuation off the end of every caption
+ * would eventually eat a name that meant it.
+ */
+export function captionName(name: string): string {
+  return name.replace(/\s*:+$/u, "");
+}
+
 /** A caption and its answer, joined the way this surface separates them. */
 function caption(name: string, body: string, style: CardBadgeStyle): string {
   // A SPACE in a chip and a COLON in a line. "Floor 3" is a caption inside a
   // border; "Floor: 3" is what the same pair has to become when the border is
   // gone and the neighbours are a dot away.
-  return style === "line" ? `${name}: ${body}` : `${name} ${body}`;
+  const head = captionName(name);
+  return style === "line" ? `${head}: ${body}` : `${head} ${body}`;
 }
 
 /**
@@ -250,11 +279,16 @@ export function cardBadgeText(
   style: CardBadgeStyle = "badge"
 ): string | undefined {
   const presentation = badgePresentation(row);
-  const name = text(row.name);
+  // Normalised ONCE, here (D455): every arm below asks "is there a name to
+  // print", and the answer has to be about the name this pair will actually
+  // draw — a row whose whole name is ":" has none.
+  const name = captionName(text(row.name));
   const unit = text(row.unit);
 
   if (presentation === "name") {
-    // The name IS the badge, and only while the answer is yes.
+    // The name IS the badge, and only while the answer is yes. Normalised by
+    // the same rule as a caption: a lone "Brick:" is a colon with nothing
+    // after it, which is the defect in its plainest form.
     return isTrue(row.value) && name.length > 0 ? name : undefined;
   }
 
@@ -288,7 +322,7 @@ export function cardBadgeText(
 function alreadyCaptioned(row: CardBadgeRow): boolean {
   const presentation = badgePresentation(row);
   if (presentation === "name") return true;
-  return presentation === "name_value" && text(row.name).length > 0;
+  return presentation === "name_value" && captionName(text(row.name)).length > 0;
 }
 
 /**
@@ -331,7 +365,10 @@ export function cardBadgeTexts(
 
   for (const positions of groups.values()) {
     if (positions.length < 2) continue;
-    const names = positions.map((at) => text(printedRows[at]?.name));
+    // The names as they will be DRAWN (D455) — so a catalogue row spelling
+    // one axis "Floor:" and the other "Floor" is two spellings of one word
+    // here rather than two distinct captions that tell a reader nothing apart.
+    const names = positions.map((at) => captionName(text(printedRows[at]?.name)));
     // Nothing to caption with, or one word for both axes: leave the line as
     // the server wrote it rather than adding a caption that tells a reader
     // nothing they did not already have.