@stapel/listings-react 0.25.10 → 0.26.0

package/src/index.ts

@@ -105,9 +105,12 @@ export type {
 
 // ── model: the two axes ──────────────────────────────────────────────────────
 export {
+  MY_LISTINGS_COUNTED_TABS,
+  MY_LISTINGS_REMOVED_TAB,
   MY_LISTINGS_TABS,
   MY_LISTINGS_TAB_STATUSES,
   MY_LISTINGS_UNTABBED_STATUSES,
+  countedTabOf,
   isPubliclyVisible,
   lifecycleCaption,
   listingStatusView,
@@ -119,6 +122,7 @@ export type {
   ListingStatusTone,
   ListingStatusView,
   ModerationNotice,
+  MyListingsCountedTab,
   MyListingsTab,
 } from "./model/status.js";
 export {
@@ -188,6 +192,7 @@ export type {
   CardBadgeContract,
   CardBadgePresentation,
   CardBadgeRow,
+  CardBadgeStyle,
 } from "./model/cardBadges.js";
 
 // ── model: the engagement axis (already-seen / view count / the overlay) ─────
@@ -310,6 +315,23 @@ export type {
   FavoritesBag,
   UseFavoritesOptions,
 } from "./headless/Favorites.js";
+export {
+  SHARE_COPIED_MS,
+  SHARE_NETWORKS,
+  Share,
+  hasNativeShare,
+  resolveShareUrl,
+  shareLinks,
+  useShare,
+} from "./headless/Share.js";
+export type {
+  ShareBag,
+  ShareChannel,
+  ShareLink,
+  ShareNetwork,
+  ShareTarget,
+  UseShareOptions,
+} from "./headless/Share.js";
 export { useListingActions } from "./headless/ListingActions.js";
 export type {
   ListingActionsBag,

package/src/model/cardBadges.ts

@@ -56,6 +56,44 @@
  * contract, and it is rendered exactly as it is rendered today — through
  * `@stapel/attributes-react`'s `<FeatureBadges>`, off the stored DAO's own
  * config. Nothing about this module is required for a card to draw.
+ *
+ * ── A CHIP IS NOT A LINE (D421) ───────────────────────────────────────────
+ *
+ * The four presentations produce a piece of text; where that text is PUT
+ * decides how it is read, and the two places this pair puts it are not the
+ * same place:
+ *
+ *   a badge strip   each element is a `<Tag>`, and the chip's own border says
+ *                   where one fact ends and the next begins;
+ *   a spec line     the elements are joined with " · ", so the only thing
+ *                   separating two facts is punctuation, and a SPACE inside
+ *                   one of them is not punctuation.
+ *
+ * Measured on a live feed, translated: "HONOR · Model 90 · 256 GB" — three
+ * facts, and the middle one reads as a value that begins with the word
+ * "Model", because in a run of values a caption joined by a space is
+ * indistinguishable from a two-word answer. So {@link CardBadgeStyle}
+ * `"line"` writes the same pair with a COLON, which is the punctuation that
+ * says "what follows is the answer to this". The chip keeps its space: "Floor 3" inside a border needs
+ * no help, and a colon there is the form-field look the 0.22 contract
+ * deliberately refused.
+ *
+ * ── …AND TWO AXES MUST NOT WEAR ONE CAPTION ───────────────────────────────
+ *
+ * The same feed: "5 fl. · 9 fl. · 54 m²" — the floor a flat is on and the
+ * number of floors in the building, printed as one number and its unit each,
+ * twice, with nothing saying which is which. The server presented both as
+ * `value_unit` and it was right about each of them ALONE; what it cannot see
+ * is that they are on one line together.
+ *
+ * That collision is a property of the SET, so it is resolved once, here, in
+ * {@link cardBadgeTexts}: elements printed without a caption that share a unit
+ * (or that print identical text) get their catalogue names back — the
+ * `name_value` shape the contract already defines, so a disambiguated element
+ * is spelled exactly as a server-captioned one. The rule refuses to act where
+ * it would not help: a group whose names are missing or not distinct is left
+ * alone rather than captioned with the same word twice, because a caption
+ * that does not tell two things apart is noise the reader still has to read.
  */
 import type { ListingCardBadgeElement, ListingFeatureDao } from "../api/types.js";
 
@@ -180,6 +218,23 @@ function isTrue(raw: unknown): boolean {
   return raw === true || raw === 1 || raw === "true";
 }
 
+/**
+ * WHERE the text is going to be put — see the module header.
+ *
+ * `"badge"` is a chip in a strip and is the default, so every existing call
+ * site keeps the bytes it had. `"line"` is one item in a " · "-separated run,
+ * where a caption needs punctuation to be read as one.
+ */
+export type CardBadgeStyle = "badge" | "line";
+
+/** 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}`;
+}
+
 /**
  * One badge element → the text a card prints, or `undefined` for an element
  * that has nothing to say (a false boolean, a blank value).
@@ -189,7 +244,11 @@ function isTrue(raw: unknown): boolean {
  * exists: three cards each re-deciding what a badge says is three places for
  * "Brick · 3 · 9" to come back.
  */
-export function cardBadgeText(row: CardBadgeRow, locale?: string): string | undefined {
+export function cardBadgeText(
+  row: CardBadgeRow,
+  locale?: string,
+  style: CardBadgeStyle = "badge"
+): string | undefined {
   const presentation = badgePresentation(row);
   const name = text(row.name);
   const unit = text(row.unit);
@@ -208,12 +267,11 @@ export function cardBadgeText(row: CardBadgeRow, locale?: string): string | unde
     case "value_unit":
       return withUnit;
     case "name_value":
-      // A SPACE, not a colon. "Floor 3" is a caption; "Floor: 3" is a form
-      // field, and a card is neither a form nor a table — the colon is the
-      // punctuation the spec list uses because a spec list IS the table.
-      // The unit rides along: a named row that dropped it reads "Mileage
-      // 20 000", which is the defect this contract exists to close.
-      return name.length > 0 ? `${name} ${withUnit}` : withUnit;
+      // Joined by the SURFACE's own punctuation (D421): a space inside a
+      // chip, a colon inside a line. The unit rides along either way — a
+      // named row that dropped it reads "Mileage 20 000", which is the defect
+      // this contract exists to close.
+      return name.length > 0 ? caption(name, withUnit, style) : withUnit;
     default:
       // `value`, and an element the server left plain in a list that speaks
       // the contract. The value alone, never the unit — the server said so.
@@ -221,17 +279,71 @@ export function cardBadgeText(row: CardBadgeRow, locale?: string): string | unde
   }
 }
 
-/** Every element that has something to say, in the server's order. */
+/**
+ * Does this element already print its own caption?
+ *
+ * `name` IS the caption, and a `name_value` with a name to print carries one.
+ * Everything else is a bare answer, and two bare answers are what can collide.
+ */
+function alreadyCaptioned(row: CardBadgeRow): boolean {
+  const presentation = badgePresentation(row);
+  if (presentation === "name") return true;
+  return presentation === "name_value" && text(row.name).length > 0;
+}
+
+/**
+ * How a bare answer could be MISTAKEN for its neighbour: by measuring the
+ * same thing (one unit, two axes) or by reading identically.
+ */
+function ambiguityKey(row: CardBadgeRow, printed: string): string {
+  const unit = text(row.unit);
+  return unit.length > 0 ? `unit:${unit}` : `text:${printed}`;
+}
+
+/**
+ * Every element that has something to say, in the server's order, with two
+ * axes that would read alike told apart — see the module header (D421).
+ */
 export function cardBadgeTexts(
   rows: readonly CardBadgeRow[],
-  locale?: string
+  locale?: string,
+  style: CardBadgeStyle = "badge"
 ): readonly { readonly slug: string; readonly text: string }[] {
   const out: { slug: string; text: string }[] = [];
+  const printedRows: CardBadgeRow[] = [];
+  /** Ambiguity key → the positions in `out` that could be confused. */
+  const groups = new Map<string, number[]>();
+
   for (const row of rows) {
-    const printed = cardBadgeText(row, locale);
-    if (printed !== undefined && typeof row.slug === "string" && row.slug.length > 0) {
-      out.push({ slug: row.slug, text: printed });
+    const printed = cardBadgeText(row, locale, style);
+    if (printed === undefined || typeof row.slug !== "string" || row.slug.length === 0) {
+      continue;
     }
+    const at = out.length;
+    out.push({ slug: row.slug, text: printed });
+    printedRows.push(row);
+    if (alreadyCaptioned(row)) continue;
+    const key = ambiguityKey(row, printed);
+    const seen = groups.get(key);
+    if (seen === undefined) groups.set(key, [at]);
+    else seen.push(at);
   }
+
+  for (const positions of groups.values()) {
+    if (positions.length < 2) continue;
+    const names = positions.map((at) => 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.
+    if (names.some((name) => name.length === 0)) continue;
+    if (new Set(names).size !== names.length) continue;
+    positions.forEach((at, index) => {
+      const entry = out[at];
+      const name = names[index];
+      if (entry === undefined || name === undefined) return;
+      out[at] = { slug: entry.slug, text: caption(name, entry.text, style) };
+    });
+  }
+
   return out;
 }

package/src/model/mineSource.ts

@@ -32,12 +32,18 @@
  */
 import type { ListingsApi } from "../api/listingsApi.js";
 import type { MyListingsParams, PaginatedMyListingCards } from "../api/types.js";
-import type { MyListingsTab } from "./status.js";
+import type { MyListingsCountedTab } from "./status.js";
 import { MY_LISTINGS_TAB_STATUSES } from "./status.js";
 
-/** One page of the caller's own listings, however the host gets them. */
+/**
+ * One page of the caller's own listings, however the host gets them.
+ *
+ * `tab` is one of the three COUNTED tabs and not the fourth: the removed tab
+ * (D407) reads takedowns off `?status=blocked` directly and unpaged, so a host
+ * source is never handed a tab it was not written for.
+ */
 export type MyListingsSource = (args: {
-  readonly tab: MyListingsTab;
+  readonly tab: MyListingsCountedTab;
   readonly page: MyListingsParams;
   readonly signal?: AbortSignal;
 }) => Promise<PaginatedMyListingCards>;

package/src/model/status.ts

@@ -285,7 +285,8 @@ export function listingStatusView(
 }
 
 /**
- * The dashboard tabs, and the statuses each one folds together.
+ * The three tabs `my/counters` COUNTS, and the statuses each one folds
+ * together.
  *
  * The grouping is the SERVER's (`views.my_counters`), copied here so a tab's
  * caption and its count cannot describe different sets: `active` includes
@@ -294,40 +295,106 @@ export function listingStatusView(
  * working on. A client that grouped them its own way would show "3 active"
  * over two rows.
  */
-export const MY_LISTINGS_TABS = ["active", "drafts", "archived"] as const;
+export const MY_LISTINGS_COUNTED_TABS = ["active", "drafts", "archived"] as const;
 
-export type MyListingsTab = (typeof MY_LISTINGS_TABS)[number];
+/** One of the three tabs `MyCountersResponse` carries a number for. */
+export type MyListingsCountedTab = (typeof MY_LISTINGS_COUNTED_TABS)[number];
 
-export const MY_LISTINGS_TAB_STATUSES: Readonly<
-  Record<MyListingsTab, readonly ListingLifecycleStatus[]>
+const COUNTED_TAB_STATUSES: Readonly<
+  Record<MyListingsCountedTab, readonly ListingLifecycleStatus[]>
 > = {
   active: ["published", "pending"],
   drafts: ["draft", "rejected"],
   archived: ["archived", "paused", "expired", "sold"],
 };
 
-/** Which tab a listing belongs to, or `undefined` for BLOCKED — the one
- * status `my/counters` counts in no tab at all. A dashboard that silently
- * dropped it would hide exactly the listing whose owner most needs to know. */
-export function tabOf(
+/** Which of the three COUNTED tabs a status belongs to, or `undefined` for
+ * one the server's own counter groups nowhere — `blocked`, today. */
+export function countedTabOf(
   status: ListingLifecycleStatus
-): MyListingsTab | undefined {
-  for (const tab of MY_LISTINGS_TABS) {
-    if (MY_LISTINGS_TAB_STATUSES[tab].includes(status)) return tab;
+): MyListingsCountedTab | undefined {
+  for (const tab of MY_LISTINGS_COUNTED_TABS) {
+    if (COUNTED_TAB_STATUSES[tab].includes(status)) return tab;
   }
   return undefined;
 }
 
 /**
- * The statuses no tab folds in — `blocked`, and nothing else today.
+ * The statuses the server's own counter groups nowhere — `blocked`, and
+ * nothing else today.
  *
  * DERIVED, not written down a second time: a status added upstream and left
  * out of the counter groupings lands here automatically and gets shown, which
  * is the opposite of what a hardcoded `["blocked"]` would do the day it goes
- * stale. The dashboard renders these rows OUTSIDE the tabs (see
- * `default/MyListingsPane.tsx`) rather than folding them into one, because a
- * tab's rows and its `my/counters` badge have to describe the same set — and
- * `my/counters` counts a takedown in no tab at all.
+ * stale.
  */
 export const MY_LISTINGS_UNTABBED_STATUSES: readonly ListingLifecycleStatus[] =
-  LISTING_STATUSES.filter((status) => tabOf(status) === undefined);
+  LISTING_STATUSES.filter((status) => countedTabOf(status) === undefined);
+
+/**
+ * The fourth tab: the rows `my/counters` counts in NO tab at all.
+ *
+ * ── What was on screen (D407) ────────────────────────────────────────────
+ *
+ * A listing pulled by moderation showed "Taken down by a moderator" over a
+ * counter row reading "Active 0 · Drafts 0 · Archived 0", beside the active
+ * tab's own "nothing of yours is live". The object was on the page and in no
+ * tab and in no number — three statements, and the two loudest of them said
+ * the seller had nothing.
+ *
+ * The takedowns had a home before this (a block above the tabs) and that was
+ * the half that was wrong: a row outside the tab strip is a row the counters
+ * do not describe, and a person reads the counters. So they get a TAB, with a
+ * count, like every other state a listing can be in.
+ *
+ * ── Why a fourth tab and not the archive ─────────────────────────────────
+ *
+ * Folding `blocked` into `archived` is the other shape this could take, and
+ * it costs the count: `my/counters` has three integers and no fourth, so an
+ * archive tab holding takedowns would read the server's `archived` number —
+ * `0` — until the tab was opened and its rows could raise it. The fourth tab
+ * is counted from its OWN read (`?status=blocked`, unpaged), so the number is
+ * right while the seller is looking at a different tab, which is exactly the
+ * moment D407 was measured at.
+ *
+ * The archive keeps its meaning too, which is not nothing: "I put this away"
+ * and "a moderator took this down" are not the same sentence and a tab that
+ * said one over rows that meant the other would be the D407 defect wearing a
+ * label.
+ */
+export const MY_LISTINGS_REMOVED_TAB = "removed";
+
+/**
+ * Every tab the dashboard can show: the server's three, then the removed one.
+ *
+ * The removed tab is DRAWN only where there is something in it (see
+ * `headless/MyListings.tsx`) — an empty "Taken down" tab is a scare — but it
+ * is in this list unconditionally, because `?tab=removed` must parse and a
+ * host must be able to name it.
+ */
+export const MY_LISTINGS_TABS: readonly [
+  ...typeof MY_LISTINGS_COUNTED_TABS,
+  typeof MY_LISTINGS_REMOVED_TAB,
+] = [...MY_LISTINGS_COUNTED_TABS, MY_LISTINGS_REMOVED_TAB];
+
+export type MyListingsTab = (typeof MY_LISTINGS_TABS)[number];
+
+export const MY_LISTINGS_TAB_STATUSES: Readonly<
+  Record<MyListingsTab, readonly ListingLifecycleStatus[]>
+> = {
+  ...COUNTED_TAB_STATUSES,
+  [MY_LISTINGS_REMOVED_TAB]: MY_LISTINGS_UNTABBED_STATUSES,
+};
+
+/** Which tab a listing belongs to. Every status has one: the three counted
+ * groupings, and the removed tab for whatever they leave out. `undefined` is
+ * unreachable today and stays in the signature so a status this build has
+ * never heard of cannot be filed under a tab by accident. */
+export function tabOf(
+  status: ListingLifecycleStatus
+): MyListingsTab | undefined {
+  for (const tab of MY_LISTINGS_TABS) {
+    if (MY_LISTINGS_TAB_STATUSES[tab].includes(status)) return tab;
+  }
+  return undefined;
+}