@stapel/listings-react 0.25.9 → 0.26.0

package/src/default/cardGallery.ts

@@ -46,9 +46,12 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { PointerEvent as ReactPointerEvent, RefObject } from "react";
+import { fontSize, radii, spacing } from "@stapel/tokens";
 
 /** The class the gallery's own box carries — see {@link cardGalleryCss}. */
 export const CARD_GALLERY_CLASS = "stapel-listing-gallery";
+/** The class the "3 of 16" pill carries — see {@link cardGalleryCss}. */
+export const CARD_GALLERY_COUNTER_CLASS = "stapel-listing-gallery-count";
 /** The `href` the hoisted gallery stylesheet is deduplicated by. */
 export const CARD_GALLERY_STYLE_HREF = "stapel-listings-card-gallery";
 
@@ -338,7 +341,35 @@ export function useCardGallery(count: number): CardGallery {
  */
 export function cardGalleryCss(): string {
   const box = `.${CARD_GALLERY_CLASS}`;
+  const counter = `.${CARD_GALLERY_COUNTER_CLASS}`;
   return [
+    // The counter is placed against this box, so the box has to be the
+    // containing block. Nothing else about the gallery changes: a `relative`
+    // with no offsets moves no pixel of what is already in it.
+    `${box}{position:relative}`,
+    // "3 of 16", bottom-TRAILING corner — the dots own the bottom centre
+    // (`SkinCarousel`: `inset-inline:0; justify-content:center`) and two
+    // indicators fighting for one spot is worse than neither.
+    //
+    // `pointer-events:none` is load-bearing rather than tidy: this box owns
+    // the hover-scrub and the swipe, and an element that swallowed a pointer
+    // would make one corner of every card's photograph dead to both gestures.
+    //
+    // A FIXED scrim and white text, not a theme role, and this is the one
+    // place in the package where that is the right answer: the pill sits on
+    // an arbitrary PHOTOGRAPH, which is neither light nor dark, so a value
+    // that followed the page's theme would be unreadable on half the photos
+    // in either one.
+    `${counter}{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;` +
+      // A counter whose digits change width makes the pill twitch on every
+      // swipe.
+      `font-variant-numeric:tabular-nums}`,
     // THE VERTICAL AXIS IS THE BROWSER'S, and is not negotiable: a card is a
     // small box in a long feed, and the one unacceptable outcome of a gallery
     // gesture is a page that will not scroll. `pan-y` says so at the platform

package/src/default/favorite.tsx

@@ -35,6 +35,8 @@ import { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
 import { HeartIcon } from "./icons.js";
+import { useNotice } from "./notice.js";
+import { LISTING_ACTIONS_STYLE_HREF, actionRowCss } from "./actionRow.js";
 
 export interface FavoriteHeartProps {
   readonly listingId: number;
@@ -83,6 +85,31 @@ export interface FavoriteHeartProps {
    * its reason, which is all a surface with no sign-in route can offer.
    */
   readonly signIn?: SignInCta;
+  /**
+   * The hit-target class this surface wants — `LISTING_CARD_ACTION_CLASS` on
+   * a card (36px with a cursor, 44px with a thumb),
+   * `LISTING_ACTION_CLASS` on the listing page (44px everywhere).
+   *
+   * A CLASS rather than a size prop: the tiers are a media query, and a
+   * component that took a number would have to be told the viewport — which
+   * is the thing a leaf must never ask. See `actionRow.ts`.
+   */
+  readonly className?: string;
+  /**
+   * SAY THE OUTCOME OUT LOUD — a short toast on each successful press.
+   *
+   * Off by default and ON for the listing page: one heart on a screen the
+   * person came to act on earns a sentence, forty hearts on a grid do not.
+   * The icon fill remains the state in both cases; this is the acknowledgement
+   * that the press was received, which is the half a small glyph pinned to
+   * the corner of a photograph cannot carry on its own.
+   *
+   * It is raised on the GESTURE, from the predicted next state, for the same
+   * reason `useFavoriteToggle` draws that state optimistically: the toast has
+   * to arrive with the press. A write that then fails rolls the icon back and
+   * states the failure through the heart's own `ErrorAlert`.
+   */
+  readonly announce?: boolean;
   readonly style?: CSSProperties;
 }
 
@@ -134,6 +161,7 @@ export interface FavoriteHeartProps {
  */
 export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   const t = useT();
+  const notice = useNotice();
   const { token } = antdTheme.useToken();
   const favorite = useFavoriteToggle(props.listingId, props.favorited);
   const label = t(
@@ -154,6 +182,22 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   // place a blocked reason becomes words in this fleet.
   const gate = useActionGate(favorite.gate);
   const reason = gate.reason;
+  // The press, plus the sentence the surface asked for. The next state is the
+  // one the icon is about to draw, so the toast and the fill say the same
+  // thing at the same moment — see `announce`.
+  const announce = props.announce === true;
+  const press = (): void => {
+    const next = !favorite.favorited;
+    favorite.toggle();
+    if (!announce || !favorite.gate.available) return;
+    notice(
+      t(
+        next
+          ? LISTINGS_I18N_KEYS.favoriteAdded
+          : LISTINGS_I18N_KEYS.favoriteRemoved
+      )
+    );
+  };
   // D431. A blocked gate plus a door the surface handed in: the press is not
   // refused, it is ROUTED — through the door, keeping whatever `?next=` the
   // container put in the href. With no door there is nothing better for the
@@ -175,9 +219,10 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
         ...doorPress,
         ...(door?.href !== undefined ? {} : { "aria-pressed": favorite.favorited }),
       }
-    : { "aria-pressed": favorite.favorited, onClick: favorite.toggle };
+    : { "aria-pressed": favorite.favorited, onClick: press };
   // A failed save, stated where the heart is. The rollback already put the
   // icon back; this says why it went back.
+  // (see `press` above for the toast that rides the successful half)
   const failure = (
     <ErrorAlert
       testId={`${props.testId}-error`}
@@ -185,8 +230,20 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
       variant="inline"
     />
   );
+  // The hit-target rules the surfaces address by class. Hoisted here rather
+  // than by each card, because the heart is what carries the class and a
+  // stylesheet that arrived only on the surfaces that remembered it is a
+  // 32px target on the one that forgot.
+  const sheet = (
+    <style href={LISTING_ACTIONS_STYLE_HREF} precedence="default">
+      {actionRowCss()}
+    </style>
+  );
+
   if (props.blockedReason === "popover" && reason !== undefined) {
     return (
+      <>
+      {sheet}
       <GateReasonPopover
         reason={reason}
         cta={props.signIn}
@@ -201,6 +258,9 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
             // control, and the disclosure stays as the hint beside it.
             {...(opensDoor ? {} : { "aria-disabled": true })}
             {...bind}
+            {...(props.className !== undefined
+              ? { className: props.className }
+              : {})}
             aria-label={label}
             data-testid={props.testId}
             data-favorited={String(favorite.favorited)}
@@ -212,9 +272,12 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
           />
         )}
       </GateReasonPopover>
+      </>
     );
   }
   return (
+    <>
+    {sheet}
     <GatedControl
       gate={favorite.gate}
       testId={props.gateTestId ?? `${props.testId}-gate`}
@@ -233,6 +296,9 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
             shape="circle"
             // See `<ListingCard>`: the substrate's binding, spread whole.
             {...bind}
+            {...(props.className !== undefined
+              ? { className: props.className }
+              : {})}
             aria-label={label}
             data-testid={props.testId}
             data-favorited={String(favorite.favorited)}
@@ -245,5 +311,6 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
         </>
       )}
     </GatedControl>
+    </>
   );
 }

package/src/default/icons.tsx

@@ -50,6 +50,66 @@ export function HeartIcon(props: HeartIconProps): ReactElement {
   );
 }
 
+/**
+ * The share glyph — three nodes and two edges, the platform-neutral shape
+ * both Android and the web draw for "send this somewhere else".
+ *
+ * `aria-hidden`, like the heart: the control it sits in carries the verb as
+ * its accessible name in every arm, including the phone arm where the word
+ * itself is not painted, and a glyph announced beside its own label reads the
+ * action twice.
+ *
+ * Deliberately not the iOS "box with an arrow": that shape means "share" to
+ * an iPhone user and "upload" or "export" to everybody else, and this control
+ * is drawn on a browser, not inside an app the platform styled.
+ */
+export function ShareIcon(): 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"
+    >
+      <circle cx="18" cy="5" r="3" />
+      <circle cx="6" cy="12" r="3" />
+      <circle cx="18" cy="19" r="3" />
+      <path d="M8.6 10.5 15.4 6.6" />
+      <path d="M8.6 13.5 15.4 17.4" />
+    </svg>
+  );
+}
+
+/**
+ * A chain link — the copy row's glyph, and the one thing on the menu that is
+ * not a network's own brand.
+ */
+export function LinkIcon(): 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="M10 13a5 5 0 0 0 7.5.6l3-3a5 5 0 0 0-7-7l-1.7 1.7" />
+      <path d="M14 11a5 5 0 0 0-7.5-.6l-3 3a5 5 0 0 0 7 7l1.7-1.7" />
+    </svg>
+  );
+}
+
 /**
  * Which way the asking price moved — an arrow, and a NAME for it.
  *

package/src/default/index.ts

@@ -71,6 +71,7 @@ export {
   DETAIL_SPLIT_MEASURE,
   DETAIL_SPLIT_ASIDE,
   DETAIL_PHOTO_MIN,
+  DETAIL_GALLERY_GUTTER,
 } from "./ListingDetailPane.js";
 export type { ListingDetailPaneProps } from "./ListingDetailPane.js";
 export {
@@ -126,6 +127,28 @@ export {
   useCardGallery,
 } from "./cardGallery.js";
 export type { CardGallery } from "./cardGallery.js";
+// ── the reader's two actions: save it, or send it to somebody ───────────────
+export { ListingActions } from "./ListingActions.js";
+export type {
+  ListingActionsConfig,
+  ListingActionsProps,
+} from "./ListingActions.js";
+export { ShareAction } from "./ShareAction.js";
+export type { ShareActionProps } from "./ShareAction.js";
+export {
+  LISTING_ACTIONS_CLASS,
+  LISTING_ACTIONS_OVERLAY_CLASS,
+  LISTING_ACTIONS_STYLE_HREF,
+  LISTING_ACTION_CLASS,
+  LISTING_ACTION_HIT,
+  LISTING_ACTION_LABEL_CLASS,
+  LISTING_CARD_ACTION_CLASS,
+  LISTING_CARD_ACTION_HIT,
+  actionRowCss,
+} from "./actionRow.js";
+export { NOTICE_SECONDS, useNotice } from "./notice.js";
+export type { Notice } from "./notice.js";
+
 export { SignInLink } from "./SignInLink.js";
 export type { SignInLinkProps } from "./SignInLink.js";
 export type { CategoryFeaturesProp, ThemeModeProp } from "./types.js";

package/src/default/notice.ts

@@ -0,0 +1,68 @@
+/**
+ * A one-line confirmation, spoken once — the message seam this skin uses and
+ * the reason it is not a new dependency.
+ *
+ * ── There is no fleet-wide toast primitive, and this does not invent one ──
+ *
+ * `@stapel/tokens-antd/skin` carries `ErrorAlert`, `EmptyState`,
+ * `GatedControl`, `SkinDialog` and `SkinConfirm` — every way a pair states a
+ * REFUSAL or asks a question — and nothing at all for "that worked". So the
+ * seam here is antd's own, which this package already renders through:
+ *
+ *   1. `App.useApp().message` when the host mounts antd's `<App>`, which is
+ *      the arrangement antd itself asks for — the notice then inherits the
+ *      host's `ConfigProvider` theme, its locale and its container;
+ *   2. antd's STATIC `message` otherwise, so a host that never mounted `<App>`
+ *      still gets the confirmation instead of silence.
+ *
+ * Outside an `<App>`, `App.useApp()` returns `{message: {}, …}` — antd's own
+ * default context — which is why the arm is chosen by asking whether the
+ * function is there rather than by asking whether a provider is. A version
+ * that assumed the context would have been a confirmation that worked in
+ * every test and on no deployment.
+ *
+ * ── And a toast is never the ONLY copy of a confirmation ──────────────────
+ *
+ * A toast is transient by construction: it appears for three seconds
+ * somewhere the person may not be looking, and on a phone it can land under a
+ * thumb. So every caller here also paints the same sentence where the gesture
+ * happened — `<ShareAction>` states "Link copied" inside the open menu, and
+ * 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.
+ */
+import { useCallback } 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;
+
+/**
+ * How long a confirmation stands, in seconds.
+ *
+ * Two, not antd's default three. Every notice this package raises confirms
+ * something the person can already SEE — a filled heart, a sentence standing
+ * in the open share menu — so it is an acknowledgement, not information, and
+ * an acknowledgement that outstays the gesture is a strip of chrome sitting
+ * over the page a thumb was about to press next.
+ */
+export const NOTICE_SECONDS = 2;
+
+export function useNotice(): Notice {
+  const app = App.useApp();
+  const contextual = app.message.success;
+  return useCallback(
+    (text: string): void => {
+      if (typeof contextual === "function") {
+        contextual(text, NOTICE_SECONDS);
+        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);
+    },
+    [contextual]
+  );
+}

package/src/headless/ListingComposer.tsx

@@ -9,7 +9,11 @@ import {
   loadReady,
 } from "@stapel/core";
 import type { ActionAvailability, FlowError, LoadState } from "@stapel/core";
-import type { FeatureDef, FeaturesDto } from "@stapel/attributes-react";
+import type {
+  FeatureChangeSource,
+  FeatureDef,
+  FeaturesDto,
+} from "@stapel/attributes-react";
 import {
   initialFeatureValues,
   toFeaturesDto,
@@ -191,6 +195,20 @@ export interface UseListingComposerOptions {
   readonly onCategoryChange?: (categoryId: string) => void;
   /** Seed for a brand-new draft (a category preselected from the URL, say). */
   readonly initialValues?: Partial<ListingDraftValues>;
+  /**
+   * Every answer to a category feature, and WHO wrote it.
+   *
+   * The composer records provenance for itself ({@link
+   * ListingComposerBag.featureSources}); this is the same fact pushed to a
+   * host that keeps its own ledger — the storefront deciding whether a
+   * generated suggestion may overwrite a field, say. It fires on every
+   * `setFeature`, including the ones nobody chose (`"cascade"`, `"bake"`).
+   */
+  onFeatureChange?: (
+    slug: string,
+    value: unknown,
+    source: FeatureChangeSource
+  ) => void;
   onDraftCreated?: (draft: ListingDraft) => void;
   onPublished?: (response: PublishResponse, outcome: PublishOutcome) => void;
 }
@@ -214,7 +232,31 @@ export interface ListingComposerBag {
     value: ListingDraftValues[K]
   ): void;
   setLocation(location: ListingLocation): void;
-  setFeature(slug: string, value: unknown): void;
+  /**
+   * Answer one category feature — and say WHO answered it.
+   *
+   * `source` is the third argument `<FeatureFields onChange>` has emitted
+   * since `@stapel/attributes-react` 0.16.4, and it was being dropped on the
+   * floor here: this bag's setter took two arguments, so the rendering half's
+   * own write-backs — a dependent field RESET because its parent moved
+   * (`"cascade"`) and a value the narrowed config left as the only possible
+   * one (`"bake"`) — arrived indistinguishable from a person typing. A host
+   * recording provenance stamped the reset as the seller's answer and locked
+   * a field holding nothing.
+   *
+   * Optional, and `"user"` when omitted: a two-argument caller keeps
+   * compiling and keeps meaning what it meant.
+   */
+  setFeature(slug: string, value: unknown, source?: FeatureChangeSource): void;
+  /**
+   * Who wrote each feature answer, keyed by slug — `"user"`, `"cascade"` or
+   * `"bake"`, and absent for an answer that arrived with the draft or from
+   * the catalogue's own default rather than through {@link setFeature}.
+   *
+   * Pruned with the values themselves when a category change drops a slug, so
+   * a slug that comes back later comes back unattributed.
+   */
+  readonly featureSources: Readonly<Record<string, FeatureChangeSource>>;
   /** Changing category keeps the answers the new schema also asks for. */
   setCategory(categoryId: string): void;
   /** Slugs cleared by the last category change — named, not silently lost. */
@@ -281,6 +323,9 @@ export function useListingComposer(
   }));
   const [showErrors, setShowErrors] = useState(false);
   const [dropped, setDropped] = useState<readonly string[]>([]);
+  const [featureSources, setFeatureSources] = useState<
+    Readonly<Record<string, FeatureChangeSource>>
+  >({});
   const [refusal, setRefusal] = useState<PublishRefusal | undefined>(undefined);
   const [outcome, setOutcome] = useState<PublishOutcome | undefined>(undefined);
   const [saved, setSaved] = useState(false);
@@ -354,7 +399,17 @@ export function useListingComposer(
         if (kept[slug] === undefined) seeded[slug] = value;
       }
       if (gone.length === 0 && Object.keys(seeded).length === 0) return current;
-      if (gone.length > 0) setDropped(gone);
+      if (gone.length > 0) {
+        setDropped(gone);
+        // The provenance goes with the value it is about. Left behind, a slug
+        // the new category happens to ask for again would come back already
+        // stamped as somebody's answer.
+        setFeatureSources((sources) =>
+          Object.fromEntries(
+            Object.entries(sources).filter(([slug]) => !gone.includes(slug))
+          )
+        );
+      }
       return { ...current, features: { ...kept, ...seeded } };
     });
   }, [schemaSettled, features]);
@@ -632,12 +687,20 @@ export function useListingComposer(
       setSaved(false);
       setValues((current) => ({ ...current, location }));
     },
-    setFeature: (slug, value) => {
+    setFeature: (slug, value, source) => {
+      // An omitted source is a person operating a control — the same default
+      // `FeatureChangeSource` states, so a two-argument host is not silently
+      // reclassified.
+      const from: FeatureChangeSource = source ?? "user";
       setSaved(false);
       setValues((current) => ({
         ...current,
         features: { ...current.features, [slug]: value },
       }));
+      setFeatureSources((current) =>
+        current[slug] === from ? current : { ...current, [slug]: from }
+      );
+      options.onFeatureChange?.(slug, value, from);
     },
     setCategory: (categoryId) => {
       setSaved(false);
@@ -659,6 +722,7 @@ export function useListingComposer(
       setRefusal(undefined);
     },
     droppedOnCategoryChange: dropped,
+    featureSources,
 
     mirror,
     fieldErrors,