@stapel/listings-react 0.30.1 → 0.30.3

package/src/default/cardGallery.ts

@@ -34,6 +34,31 @@
  * {@link SWIPE_AXIS_RATIO}. A diagonal thumb scrolling the feed changes no
  * photograph.
  *
+ * ── HOW FAR IS FAR ENOUGH, and how many photographs that buys ────────────
+ *
+ * Intent is not a commit. A drag that has declared itself horizontal still
+ * has to EARN the photograph, and the price is a fraction of the photograph
+ * itself — {@link SWIPE_COMMIT_FRACTION} of the SLIDE's own measured width,
+ * never a pixel constant. The constant was the defect, and measurably so: a
+ * one-column search card on a 390px phone is a ~351px slide (the well less
+ * the carousel's 8% peek), so a fixed 32px priced a photograph at 9% of
+ * itself; the same 32px on the two-column home feed is 19% of a ~170px slide.
+ * One number, two different gestures, and the cheap one is the one the owner
+ * met — "it feels like 10%", and the middle photograph flying past.
+ *
+ * Two further rules, and both are about a gesture being ONE decision:
+ *
+ *  - A flick is a choice too. Under the distance, a drag thrown faster than
+ *    {@link SWIPE_FLICK_VELOCITY} still advances — the speed says the intent
+ *    the distance did not.
+ *  - ONE photograph per gesture, and one only. The old handler moved its own
+ *    origin on each commit, so a drag across three slide widths advanced
+ *    three photographs (and a fling across the card advanced ten). A gesture
+ *    now commits at most once, and a second photograph costs a second press.
+ *
+ * Below the threshold the strip goes back to the picture it was showing —
+ * a refused gesture must leave the strip where it found it, not halfway.
+ *
  * ── What neither gesture touches ─────────────────────────────────────────
  *
  * The keyboard, and the card's single link target. The strip underneath is
@@ -59,14 +84,56 @@ export const CARD_GALLERY_STYLE_HREF = "stapel-listings-card-gallery";
 export const SCRUB_MEDIA = "(hover: hover) and (pointer: fine)";
 
 /**
- * How far a finger travels before it has said "photo", in CSS pixels.
+ * How far a finger travels before it is a GESTURE at all, in CSS pixels.
  *
  * Under this, a drag is a tap that wobbled — and a tap on a card is a
  * navigation, so a low threshold does not change a photograph, it changes one
  * and then leaves the listing.
+ *
+ * This is the floor, not the price: what actually buys a photograph is
+ * {@link SWIPE_COMMIT_FRACTION} of the slide, or a flick above
+ * {@link SWIPE_FLICK_VELOCITY}. A pixel count cannot be the price, because
+ * the same 32px is a third of a card in a four-column desktop grid and a
+ * twelfth of one on a phone.
  */
 export const SWIPE_MIN_PX = 32;
 
+/**
+ * How much of ONE PHOTOGRAPH a slow drag must cover to turn it, as a fraction
+ * of that photograph's own measured width.
+ *
+ * The owner's ruling, third pass: "maybe not 75, maybe 30 — right now it
+ * feels like 10%". 10% is what the old fixed 32px came to on a phone slide of
+ * ~350px, and it is why a middle photograph flew past on a gesture aimed at
+ * the feed. 0.3 is far enough that the drag is unmistakably a drag and short
+ * enough that a thumb can make it without crossing the whole card.
+ */
+export const SWIPE_COMMIT_FRACTION = 0.3;
+
+/**
+ * The speed, in CSS pixels per millisecond, at which a SHORT drag still turns
+ * the photograph.
+ *
+ * 0.5 px/ms — 500 px/s — is the owner's number and sits in the empty band
+ * between the two gestures it has to tell apart: a deliberate slow drag runs
+ * at 100–300 px/s (a thumb crossing a 350px card in one to three seconds),
+ * and a flick people expect to throw the strip runs at 800–2000 px/s. Nothing
+ * a person means as a careful drag arrives here, and nothing they mean as a
+ * flick falls under it.
+ */
+export const SWIPE_FLICK_VELOCITY = 0.5;
+
+/**
+ * The window the speed is measured over, in milliseconds.
+ *
+ * A flick is what the finger was doing AS IT LEFT, not the average of the
+ * whole gesture: a drag that crawls for a second and is then thrown would
+ * average out to a crawl, and the throw is the part the person meant. One
+ * moving window of roughly six frames is long enough to survive a single
+ * jittery sample and short enough to still be about the end of the gesture.
+ */
+export const SWIPE_VELOCITY_WINDOW_MS = 100;
+
 /**
  * How much more horizontal than vertical a drag must be to count.
  *
@@ -90,18 +157,60 @@ export function segmentIndex(offsetX: number, width: number, count: number): num
 
 /**
  * A drag → the number of photographs it asks for: `1` forward, `-1` back, `0`
- * for a drag that has not declared horizontal intent.
+ * for a drag that has not earned one.
  *
  * Dragging LEFT advances, the direction the content moves under the finger —
- * the same mapping the native scroller has.
+ * the same mapping the native scroller has. The answer is never outside
+ * `-1…1`: a gesture is worth one photograph however far it travelled, which
+ * is what stops a fling crossing the whole strip.
+ *
+ * @param dx         Horizontal travel from the press, signed, in CSS pixels.
+ * @param dy         Vertical travel from the press, signed.
+ * @param slideWidth The measured width of ONE slide. `0` means it could not
+ *   be measured (an unlaid-out strip, a server render) — and an unknown width
+ *   has no fraction, so the decision falls back to {@link SWIPE_MIN_PX}
+ *   alone rather than to an invented number.
+ * @param velocity   The finger's recent speed in CSS pixels per millisecond.
  */
-export function swipeStep(dx: number, dy: number): -1 | 0 | 1 {
+export function swipeStep(
+  dx: number,
+  dy: number,
+  slideWidth = 0,
+  velocity = 0
+): -1 | 0 | 1 {
   const across = Math.abs(dx);
+  // Is this a gesture at all — past the tap wobble, and across rather than
+  // down the page.
   if (across < SWIPE_MIN_PX) return 0;
   if (across <= Math.abs(dy) * SWIPE_AXIS_RATIO) return 0;
+  // Has it earned a photograph: the distance rule, measured against THIS
+  // strip's slide, or the speed rule when the distance is short.
+  const far = slideWidth > 0 ? across >= slideWidth * SWIPE_COMMIT_FRACTION : true;
+  if (!far && velocity < SWIPE_FLICK_VELOCITY) return 0;
   return dx < 0 ? 1 : -1;
 }
 
+/**
+ * The width of ONE slide inside this gallery's strip, in CSS pixels.
+ *
+ * Read off the SLIDE, which is the house rule (§83: geometry from the
+ * element's width, never the viewport's) and here also the only correct
+ * answer: a slide is the well less the carousel's peek, so the well's width
+ * is 8% too generous and a viewport-derived number is not about this card at
+ * all — the same card is full-bleed on a phone and a quarter of a row on a
+ * desktop grid.
+ *
+ * `0` when nothing can be measured. That is a refusal to guess, not a
+ * measurement: {@link swipeStep} falls back to the pixel floor for it.
+ */
+export function measureSlideWidth(box: HTMLElement): number {
+  const strip = box.querySelector<HTMLElement>("[data-stapel-carousel-strip]");
+  if (strip === null) return 0;
+  const slide = strip.children.item(0);
+  const width = slide === null ? 0 : slide.getBoundingClientRect().width;
+  return width > 0 ? width : 0;
+}
+
 /** Does this environment have a real pointer? `false` where there is no
  * `matchMedia` to ask (a server render, an old jsdom), which is the safe
  * side: a scrub that does not happen costs a hover, a scrub on a phone is a
@@ -198,6 +307,63 @@ function showSlide(box: HTMLElement, index: number, instant: boolean): void {
   }
 }
 
+/** One position of the finger, in time — the raw material of a flick. */
+interface Sample {
+  readonly x: number;
+  readonly t: number;
+}
+
+/** The drag in progress. Everything a release has to decide on. */
+interface Drag {
+  /** Where the finger went down. */
+  readonly x: number;
+  readonly y: number;
+  /** One slide's width, measured ONCE at the press: a strip whose geometry
+   * changed mid-gesture would move the goalposts under the finger. */
+  readonly width: number;
+  /** The recent trail, newest last — see {@link SWIPE_VELOCITY_WINDOW_MS}. */
+  samples: Sample[];
+  /** Has this gesture already spent its one photograph. */
+  committed: boolean;
+  /** Has it declared horizontal intent — the only kind of refused gesture
+   * that is worth snapping back from. */
+  crossed: boolean;
+}
+
+/** When this event happened, on whatever clock the environment has. A UA
+ * stamps every input event; the fallback is for a synthesised one. */
+function stampOf(event: { timeStamp: number }): number {
+  const stamp = event.timeStamp;
+  if (Number.isFinite(stamp) && stamp > 0) return stamp;
+  return typeof performance === "object" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+/** Record a position, and forget the ones the speed window has passed. */
+function sample(drag: Drag, x: number, t: number): void {
+  drag.samples.push({ x, t });
+  // Drop the oldest only while the NEXT one is still inside the window, so
+  // the trail always spans at least one interval to divide by.
+  while (drag.samples.length > 2) {
+    const second = drag.samples[1];
+    if (second === undefined || t - second.t <= SWIPE_VELOCITY_WINDOW_MS) break;
+    drag.samples.shift();
+  }
+}
+
+/** The finger's speed over the trail, in CSS pixels per millisecond. `0`
+ * where the environment gave no usable clock — an unknown speed is not a
+ * flick. */
+function velocityOf(drag: Drag): number {
+  const first = drag.samples[0];
+  const last = drag.samples[drag.samples.length - 1];
+  if (first === undefined || last === undefined) return 0;
+  const elapsed = last.t - first.t;
+  if (elapsed <= 0) return 0;
+  return Math.abs(last.x - first.x) / elapsed;
+}
+
 /**
  * The gallery gestures for a media well holding `count` photographs.
  *
@@ -208,9 +374,9 @@ export function useCardGallery(count: number): CardGallery {
   const ref = useRef<HTMLDivElement | null>(null);
   const [active, setActive] = useState(0);
   const [scrubbing, setScrubbing] = useState(false);
-  // The origin of the drag in progress, or `null`. A ref rather than state:
-  // it changes on every move and no render depends on it.
-  const origin = useRef<{ x: number; y: number } | null>(null);
+  // The drag in progress, or `null`. A ref rather than state: it changes on
+  // every move and no render depends on it.
+  const drag = useRef<Drag | null>(null);
   /**
    * THE INDEX THIS HOOK ASKED FOR, and the whole of the fix.
    *
@@ -276,15 +442,23 @@ export function useCardGallery(count: number): CardGallery {
         request(segmentIndex(event.clientX - rect.left, rect.width, count));
         return;
       }
-      const from = origin.current;
-      if (from === null) return;
-      const step = swipeStep(event.clientX - from.x, event.clientY - from.y);
+      const current = drag.current;
+      if (current === null) return;
+      sample(current, event.clientX, stampOf(event));
+      // ONE PHOTOGRAPH PER GESTURE. The trail keeps being recorded — a
+      // release still wants to know how the finger was moving — but the
+      // decision below is made once and the rest of the drag is scenery.
+      if (current.committed) return;
+      const dx = event.clientX - current.x;
+      const dy = event.clientY - current.y;
+      if (Math.abs(dx) >= SWIPE_MIN_PX && Math.abs(dx) > Math.abs(dy) * SWIPE_AXIS_RATIO) {
+        current.crossed = true;
+      }
+      const step = swipeStep(dx, dy, current.width, velocityOf(current));
       if (step === 0) return;
-      // The origin moves with the commit, so a long drag walks the strip one
-      // photograph per threshold rather than one per gesture.
-      origin.current = { x: event.clientX, y: event.clientY };
+      current.committed = true;
       setScrubbing(false);
-      request((current) => Math.min(count - 1, Math.max(0, current + step)));
+      request((at) => Math.min(count - 1, Math.max(0, at + step)));
     },
     [count, fine, many, request]
   );
@@ -292,18 +466,48 @@ export function useCardGallery(count: number): CardGallery {
   const onPointerDown = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>): void => {
       if (!many || event.pointerType === "mouse") return;
-      origin.current = { x: event.clientX, y: event.clientY };
+      const box = ref.current;
+      drag.current = {
+        x: event.clientX,
+        y: event.clientY,
+        // Measured here, from the slide itself, and held for the gesture.
+        width: box === null ? 0 : measureSlideWidth(box),
+        samples: [{ x: event.clientX, t: stampOf(event) }],
+        committed: false,
+        crossed: false,
+      };
     },
     [many]
   );
 
+  /**
+   * The finger leaves.
+   *
+   * A gesture that earned its photograph already took it, mid-drag, the
+   * moment it crossed the threshold. What is left here is the REFUSED one: a
+   * drag that went sideways far enough to be read as a swipe and then stopped
+   * short. The strip goes back to the photograph it was showing, because a
+   * refused gesture that leaves the strip halfway is the defect wearing the
+   * other face.
+   *
+   * A release with no drag behind it touches nothing at all — that is the
+   * guard probe p23 bought: `pointerup` also arrives after a NATIVE scroll
+   * this hook never started, and scrolling "back" there means undoing the
+   * person's own swipe.
+   */
   const endDrag = useCallback((): void => {
-    origin.current = null;
-  }, []);
+    const current = drag.current;
+    drag.current = null;
+    if (current === null || !many) return;
+    if (current.committed || !current.crossed) return;
+    const box = ref.current;
+    if (box === null) return;
+    showSlide(box, active, false);
+  }, [active, many]);
 
   const onPointerLeave = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>): void => {
-      origin.current = null;
+      drag.current = null;
       if (!many) return;
       // THE REWIND IS A HOVER RULE, AND ONLY A HOVER RULE.
       //

package/src/default/detailGallery.ts

@@ -215,6 +215,15 @@ export function detailGalleryCss(): string {
 .${LISTINGS_GALLERY_CLASS}[data-gallery-layout="strip"] > * {
   flex: 0 0 ${LISTINGS_GALLERY_STRIP_BASIS};
   scroll-snap-align: start;
+  /* EVERY PHOTOGRAPH IS A DESTINATION, not a waypoint. A mandatory snap type
+     alone only promises the strip will COME TO REST on a snap point — a fling
+     with any momentum behind it still crosses two or three photographs on its
+     way there, which is the owner's "the middle photo flies past" in its
+     native form. "always" makes the scroller stop at the first snap point it
+     reaches, so one gesture is one photograph here for the same reason the
+     card's gesture layer clamps its own step to one. The same declaration
+     SkinCarousel already carries on its slides. */
+  scroll-snap-stop: always;
 }
 .${LISTINGS_GALLERY_FRAME_CLASS} {
   position: relative;

package/src/default/index.ts

@@ -176,9 +176,13 @@ export type { CardBadgesProps } from "./CardBadges.js";
 // ── the card gallery's two gestures ─────────────────────────────────────────
 export {
   SWIPE_AXIS_RATIO,
+  SWIPE_COMMIT_FRACTION,
+  SWIPE_FLICK_VELOCITY,
   SWIPE_MIN_PX,
+  SWIPE_VELOCITY_WINDOW_MS,
   cardGalleryCss,
   hasFinePointer,
+  measureSlideWidth,
   segmentIndex,
   swipeStep,
   useCardGallery,

package/src/headless/ListingComposer.tsx

@@ -39,7 +39,6 @@ import {
   draftValuesFromWire,
   droppedFeatureSlugs,
   emptyDraftValues,
-  retainKnownFeatureValues,
 } from "../model/draft.js";
 import type { ListingDraftValues, ListingLocation } from "../model/draft.js";
 import { asFeatureDaoList } from "../model/features.js";
@@ -383,12 +382,53 @@ export function useListingComposer(
   const schemaSettled =
     options.featuresLoading !== true && options.featuresError === undefined;
   const { features } = options;
+  /**
+   * WHICH SCHEMA THIS IS, by its content and not by its identity (D455).
+   *
+   * Hosts hand `features` as a fresh array on most renders — the storefront's
+   * comes out of a query mapper — so array identity says "a render happened",
+   * never "the questions changed". The value judge below may only run on the
+   * second, and this is how the two are told apart.
+   */
+  const schemaKey = useMemo(
+    () =>
+      features
+        .map((feature) => `${feature.slug}:${JSON.stringify(feature.config ?? null)}`)
+        .join("|"),
+    [features]
+  );
+  /** The schema the values were last judged against — `null` until the first
+   * one settles. */
+  const judgedSchema = useRef<string | null>(null);
   useEffect(() => {
     if (!schemaSettled || features.length === 0) return;
+    /* A DIFFERENT SCHEMA, not merely a different render.
+     *
+     * `false` on the very first settle, which is a REOPEN and not a switch:
+     * the answers came back from the server that stored them, and re-judging
+     * them against the catalogue as it stands today would silently delete a
+     * draft's contents on the way in. */
+    const switched = judgedSchema.current !== null && judgedSchema.current !== schemaKey;
+    judgedSchema.current = schemaKey;
     setValues((current) => {
-      const gone = droppedFeatureSlugs(current.features, features);
+      /* On a SWITCH, `gone` is "what this schema will not carry": since
+         0.30.2 that includes an answer whose slug survives but whose VALUE
+         this category refuses — two leaves both declaring `color` differ in
+         the options behind it (D455). Otherwise it stays the older, narrower
+         question — "which slugs is this schema not asking about?" — because
+         within ONE category a value the mirror refuses is a person typing,
+         and deleting that is the composer editing them mid-sentence. */
+      const gone = switched
+        ? droppedFeatureSlugs(current.features, features)
+        : Object.keys(current.features)
+            .filter((slug) => !features.some((feature) => feature.slug === slug))
+            .sort();
       const kept =
-        gone.length === 0 ? current.features : retainKnownFeatureValues(current.features, features);
+        gone.length === 0
+          ? current.features
+          : Object.fromEntries(
+              Object.entries(current.features).filter(([slug]) => !gone.includes(slug))
+            );
       // `FeatureDef.default` (and the type's own default) is what the CATALOGUE
       // says a blank form opens with — a `select` option flagged `default`, a
       // preset date. It is applied ONLY where the draft has no answer: a
@@ -412,7 +452,7 @@ export function useListingComposer(
       }
       return { ...current, features: { ...kept, ...seeded } };
     });
-  }, [schemaSettled, features]);
+  }, [schemaSettled, features, schemaKey]);
 
   // The gallery is the upload bag's, whenever there is one: two sources of
   // truth for the same list is how a publish sends photos the person removed.

package/src/model/draft.ts

@@ -13,7 +13,11 @@
  * assert the BODY a save sends rather than the fact that it sent one.
  */
 import type { FeatureDef, FeaturesDto } from "@stapel/attributes-react";
-import { fromFeaturesDto, toFeaturesDto } from "@stapel/attributes-react";
+import {
+  fromFeaturesDto,
+  mirrorValidate,
+  toFeaturesDto,
+} from "@stapel/attributes-react";
 import type {
   ListingDetail,
   ListingDraft,
@@ -350,8 +354,80 @@ export function createDraftBody(categoryId?: string): ListingDraftPatch {
 }
 
 /**
- * Switching category: keep the answers whose slug the new schema also
- * declares, drop the rest.
+ * A SHARED SLUG IS NOT A SHARED ANSWER (D455).
+ *
+ * Retention used to ask one question — "does the new schema declare this
+ * slug?" — and a slug is the cheapest half of the answer. Measured on the
+ * live stand, 2026-09-12: the analysis read a photo as the wristwatch leaf
+ * and answered the colour with `zolotoy`, which that leaf offers; the
+ * category was then corrected to the laptop leaf, which declares `color` too
+ * and therefore KEPT the value — but its sixteen options spell gold
+ * `zolotistyy`, not `zolotoy`. The control drew the raw code, the mirror
+ * refused it `not_in_options`, and the publish gate shut on the colour field
+ * over a row the catalogue marks OPTIONAL and the server publishes without
+ * (`validate-draft` -> `valid: true`). The seller cannot read the demand and
+ * the gate cannot be cleared by answering what it names.
+ *
+ * So the question is asked of the VALUE: a retained answer must be one the
+ * new schema would accept. The judge is `mirrorValidate` — the very function
+ * the publish gate reads — so a value kept here can never be one the gate
+ * refuses, and the two cannot drift. Same invariant `acceptableAiWrites`
+ * states for the analysis's writes, now held for the person's own.
+ *
+ * Only a value that is BOTH present and non-blank can be dropped this way.
+ * A blank one has nothing to lose, and its `mandatory_missing` row is a
+ * demand for an answer rather than a verdict on one — naming it as "dropped"
+ * would tell a person their answer did not apply when they never gave one.
+ * A rule set the mirror cannot parse fails the batch on `_root` and drops
+ * nothing: the schema is broken, not the draft.
+ */
+function judgeRetention(
+  values: Readonly<Record<string, unknown>>,
+  features: readonly FeatureDef[]
+): { readonly kept: Record<string, unknown>; readonly dropped: string[] } {
+  const known = new Set(features.map((feature) => feature.slug));
+  const kept: Record<string, unknown> = {};
+  const dropped: string[] = [];
+  for (const [slug, value] of Object.entries(values)) {
+    if (known.has(slug)) kept[slug] = value;
+    else dropped.push(slug);
+  }
+
+  let refused: ReadonlySet<string>;
+  try {
+    const batch = mirrorValidate(features, toFeaturesDto(features, kept));
+    refused = new Set(
+      batch.results
+        .filter((result) => result.status !== "ok")
+        .map((result) => result.slug)
+    );
+  } catch {
+    // A schema this build cannot judge is not a reason to delete answers.
+    return { kept, dropped: dropped.sort() };
+  }
+
+  const survived: Record<string, unknown> = {};
+  for (const [slug, value] of Object.entries(kept)) {
+    if (refused.has(slug) && answeredFeatureValue(value)) dropped.push(slug);
+    else survived[slug] = value;
+  }
+  return { kept: survived, dropped: dropped.sort() };
+}
+
+/**
+ * Does this value count as an answer? An empty list is what clearing the last
+ * chip leaves behind — an unanswered field, not an answer of `[]`.
+ */
+function answeredFeatureValue(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "string") return value.trim().length > 0;
+  return true;
+}
+
+/**
+ * Switching category: keep the answers the new schema also asks for AND would
+ * accept, drop the rest.
  *
  * Spec §4.1 asks for exactly this, and the reason is the same one the forms
  * spec gives for `error.409.forms_version_superseded`: a person who picked
@@ -359,30 +435,25 @@ export function createDraftBody(categoryId?: string): ListingDraftPatch {
  * phones" should not retype what both categories ask for. A value whose slug
  * is gone IS dropped, because 0.6.0 rejects an unknown slug per feature —
  * carrying it would turn a category change into a publish refusal about a
- * field the composer no longer draws.
+ * field the composer no longer draws. Since 0.30.2 a value whose slug SURVIVES
+ * but which the new schema refuses is dropped for the same reason, which is
+ * the harm rather than the mechanism — see {@link judgeRetention}.
  */
 export function retainKnownFeatureValues(
   values: Readonly<Record<string, unknown>>,
   features: readonly FeatureDef[]
 ): Readonly<Record<string, unknown>> {
-  const known = new Set(features.map((feature) => feature.slug));
-  const out: Record<string, unknown> = {};
-  for (const [slug, value] of Object.entries(values)) {
-    if (known.has(slug)) out[slug] = value;
-  }
-  return out;
+  return judgeRetention(values, features).kept;
 }
 
-/** Slugs that were answered and are NOT in the new schema — what
- * {@link retainKnownFeatureValues} just dropped. A composer tells the person
- * ("2 answers do not apply to this category") instead of losing them
- * silently. */
+/** Slugs that were answered and the new schema will not carry — what
+ * {@link retainKnownFeatureValues} just dropped, whether because the slug is
+ * gone or because the answer is not one this category offers. A composer
+ * tells the person ("2 answers do not apply to this category") instead of
+ * losing them silently. */
 export function droppedFeatureSlugs(
   values: Readonly<Record<string, unknown>>,
   features: readonly FeatureDef[]
 ): readonly string[] {
-  const known = new Set(features.map((feature) => feature.slug));
-  return Object.keys(values)
-    .filter((slug) => !known.has(slug))
-    .sort();
+  return judgeRetention(values, features).dropped;
 }