@stapel/listings-react 0.27.0 → 0.28.0

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;
 }
 
 /**