@stapel/listings-react 0.27.0 → 0.28.1

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

package/src/default/index.ts

@@ -155,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/notice.ts

@@ -30,13 +30,43 @@
  * the heart's state is on the heart. This is the AMPLIFIER, never the record.
  * A future `SkinNotice` in the substrate replaces the body of this function
  * and nothing else; the callers already speak in resolved sentences.
+ *
+ * ── An amplifier may not outlive what it amplifies ────────────────────────
+ *
+ * Both arms hand the notice to a holder MOUNTED OUTSIDE this component tree —
+ * antd's `<App>` holder in the first arm, and in the second a React root antd
+ * renders into the document the first time the static entry is called. Neither
+ * is unmounted by unmounting the surface that spoke, and a standing notice is
+ * not an idle DOM node: `@rc-component/notification` counts its two seconds
+ * down with a `requestAnimationFrame` LOOP (`useNoticeTimer`), which is live
+ * work driven from a root nothing in this package owns.
+ *
+ * So the notices raised here are RETIRED when the surface that raised them
+ * goes. Two things follow, and both are the intent:
+ *
+ *  - a person who presses the heart and immediately navigates away does not
+ *    get "Saved" floating over the next page, about a listing they left;
+ *  - nothing this pair started keeps running after the tree it started in is
+ *    gone. Measured as CI flake: the detail page's heart toast kept stepping
+ *    its rAF loop past the end of the test file that raised it, and the frame
+ *    that landed after the environment was torn down threw
+ *    `ReferenceError: window is not defined` out of react-dom — from a suite
+ *    in which every test had passed.
  */
-import { useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { App, message as staticMessage } from "antd";
 
 /** Say one short sentence. Resolved copy — this is the skin, not a bag. */
 export type Notice = (text: string) => void;
 
+/**
+ * What antd hands back for a raised notice: CALL it to close the notice early,
+ * `then` it to learn that it closed on its own. Typed structurally rather than
+ * imported (`antd/es/message/interface`) so this file keeps to antd's public
+ * entry — the shape is antd's documented `MessageType` either way.
+ */
+type RaisedNotice = (() => void) & PromiseLike<unknown>;
+
 /**
  * How long a confirmation stands, in seconds.
  *
@@ -51,18 +81,40 @@ export const NOTICE_SECONDS = 2;
 export function useNotice(): Notice {
   const app = App.useApp();
   const contextual = app.message.success;
+  // The notices this surface has raised and that have not closed themselves
+  // yet — see the header. A notice retires itself the moment it closes, so
+  // this holds at most the handful still on screen.
+  const standing = useRef<Set<RaisedNotice>>(new Set());
+  useEffect(
+    () => () => {
+      const open = standing.current;
+      standing.current = new Set();
+      for (const close of open) close();
+    },
+    []
+  );
+  const hold = useCallback((raised: RaisedNotice): void => {
+    standing.current.add(raised);
+    const retire = (): void => {
+      standing.current.delete(raised);
+    };
+    // Closed by its own timer, by our unmount, or by a host calling
+    // `message.destroy()` — every ending resolves this, and a rejection is an
+    // ending too. Nothing is awaited: the notice is already on screen.
+    raised.then(retire, retire);
+  }, []);
   return useCallback(
     (text: string): void => {
       if (typeof contextual === "function") {
-        contextual(text, NOTICE_SECONDS);
+        hold(contextual(text, NOTICE_SECONDS) as RaisedNotice);
         return;
       }
       // No `<App>` above us. antd's static entry renders its own holder into
       // the document, which is exactly right for a host that never opted in,
       // and is a no-op on a server where there is no document to render into.
       if (typeof document === "undefined") return;
-      staticMessage.success(text, NOTICE_SECONDS);
+      hold(staticMessage.success(text, NOTICE_SECONDS) as RaisedNotice);
     },
-    [contextual]
+    [contextual, hold]
   );
 }

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.

package/src/model/draft.ts

@@ -224,6 +224,28 @@ function toWireFeatures(
   return toFeaturesDto(features, values) as unknown as WireFeaturesDraft;
 }
 
+/** One field of the `save-draft` body, by the name the wire uses. */
+export type ListingDraftField = keyof ListingDraftPatch;
+
+/** Options for {@link draftPatchFromValues}. */
+export interface DraftPatchOptions {
+  /**
+   * NAME THE FIELDS THIS SAVE IS WRITING, and the body carries no others.
+   *
+   * `save-draft` REPLACES every field in the body — it does not merge — so a
+   * body is not "the values I have", it is "the fields I am claiming". A save
+   * fired by one control (a photo settling, a blurred title) previously
+   * claimed all fourteen, which is only harmless while every one of them is
+   * loaded and true.
+   *
+   * Given, only these keys are spelled; the omission rules below still apply
+   * inside the selection, so naming `features_draft` without a schema still
+   * writes nothing. Absent, the whole body is sent, which is right for the
+   * composer's own save — it holds every value on the form.
+   */
+  readonly fields?: readonly ListingDraftField[];
+}
+
 /**
  * The composer's values → the `save-draft` body.
  *
@@ -234,12 +256,34 @@ function toWireFeatures(
  * (`error.400.listing_feature_not_allowed`), which is why
  * {@link retainKnownFeatureValues} prunes on the way in rather than letting
  * the server explain it.
+ *
+ * ── NO SCHEMA IS NOT AN EMPTY ANSWER SHEET ───────────────────────────────
+ *
+ * An absent or empty `features` used to produce `features_draft: {}`, and
+ * `save-draft` REPLACES that map rather than merging into it — so a save that
+ * left before the category's schema arrived DELETED every characteristic the
+ * row was holding, while the form on screen still showed them. Measured by a
+ * live container over two cold loads of one draft: a reopen's own
+ * settled-photo save fires in the first commit, before the row's category has
+ * even been adopted, and the row alternated between the draft's answers and
+ * none of them (a client storefront's README, "Named gaps").
+ *
+ * `{}` is a claim — "this listing has no characteristics" — and a caller with
+ * no schema is in no position to make it. So the key is OMITTED entirely
+ * whenever there is no schema to tag values with, and `save-draft` then
+ * leaves the stored map exactly as it was. A category that genuinely declares
+ * no features writes nothing either, which is the same answer arrived at
+ * honestly: there is nothing to say and the row already says it.
+ *
+ * {@link DraftPatchOptions.fields} is the general form of the same rule — a
+ * save that names what it is writing cannot erase what it is not.
  */
 export function draftPatchFromValues(
   values: ListingDraftValues,
-  features: readonly FeatureDef[]
+  features: readonly FeatureDef[] | undefined,
+  options: DraftPatchOptions = {}
 ): ListingDraftPatch {
-  return {
+  const full: ListingDraftPatch = {
     // Omitted while unchosen rather than sent as `""`: a draft is allowed to
     // have no category (0.21.4), and `""` is not "no category" on the wire —
     // it is an empty id the serializer refuses. The category is written by
@@ -258,7 +302,11 @@ export function draftPatchFromValues(
     // sent here is discarded. Sending one would be a claim the wire ignores.
     lat_draft: values.location.lat,
     lon_draft: values.location.lon,
-    features_draft: toWireFeatures(features, values.features),
+    // Omitted, not emptied, when there is no schema to tag with — see the
+    // doc above. `{}` is a claim about the listing; silence is not.
+    ...(features !== undefined && features.length > 0
+      ? { features_draft: toWireFeatures(features, values.features) }
+      : {}),
     countable: values.countable,
     // The pair mirrors the model's cross-field rule rather than sending a
     // contradiction: a service carries no quantity, and `validate_countable
@@ -266,6 +314,16 @@ export function draftPatchFromValues(
     stock_quantity: values.countable ? values.stockQuantity : null,
     auto_republish: values.autoRepublish,
   };
+  const named = options.fields;
+  if (named === undefined) return full;
+  // A selection, not a second body: the field's VALUE is still whatever the
+  // rules above produced, so a named field the rules omit stays omitted.
+  const wanted = new Set<string>(named);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(full)) {
+    if (wanted.has(key)) out[key] = value;
+  }
+  return out as ListingDraftPatch;
 }
 
 /**