@bytebrand/fe-ui-core-autobahn 1.0.127 → 1.0.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/fe-ui-core-autobahn",
-  "version": "1.0.127",
+  "version": "1.0.130",
   "description": "auto.de md3 (Autobahn) design system — UI primitives, cards, chrome, VDP modules, theme CSS and locales. Ships raw TypeScript source (like fe-ui-core before it); each consumer's bundler compiles it.",
   "main": "index.ts",
   "license": "UNLICENSED",

package/theme/md3.css

@@ -3628,9 +3628,9 @@ line-height: 31px;
    Breakpoints: tablet ≤ 980px, phone ≤ 600px.
    ========================================================================== */
 .md3 .container {
-  max-width: 1180px;
+  max-width: 1230px;
   margin: 0 auto;
-  width: 100%;
+  padding: 15px 15px;
 }
 
 .md3 .hero-grid {
@@ -3665,6 +3665,14 @@ line-height: 31px;
   grid-template-columns: repeat(2, 1fr);
   gap: 18px;
 }
+/* fe-landing TopResults ("Top {Make} Angebote") only — a dedicated class rather than
+   reusing .cards-2 (Alternatives also uses that, and must stay 2-up) or .cards-3
+   (shared much more widely: VDP's "Ähnliche Fahrzeuge", elsewhere). */
+.md3 .top-results-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 24px;
+}
 .md3 .cards-offers {
   display: grid;
   grid-template-columns: repeat(3, 1fr);
@@ -6565,7 +6573,9 @@ line-height: 31px;
    overrides below — kept as real CSS rules (not inline styles) since an inline style on the
    element would always beat the media-query override regardless of specificity. */
 .md3 .topbar-container {
-  padding: 0 16px;
+  max-width: 1230px;
+  margin: 0 auto;
+  padding: 15px 15px;
 }
 .md3 .topbar-actions {
   gap: 16px;
@@ -7000,12 +7010,17 @@ line-height: 31px;
 
 @media (max-width: 600px) {
   .md3 .cards-3,
-  .md3 .cards-2 {
+  .md3 .cards-2,
+  .md3 .top-results-grid {
     grid-template-columns: 1fr;
   }
-  /* fe-landing (/angebot) TopResults + Alternatives grids — shared side gutter,
-     same 12px pattern as .md3 .container elsewhere. .cards-3 is untouched (not
-     used with this gutter treatment; only .cards-2 callers asked for it). */
+  .md3 .top-results-grid {
+    gap: 16px;
+  }
+  /* fe-landing (/angebot) Alternatives grid — shared side gutter, same 12px
+     pattern as .md3 .container elsewhere. .cards-3 is untouched (not used with
+     this gutter treatment). .top-results-grid deliberately excluded — its own
+     container already handles horizontal spacing, this padding was redundant. */
   .md3 .cards-2 {
     padding-left: 12px !important;
     padding-right: 12px !important;

package/ui/CardCarousel.tsx

@@ -1,4 +1,22 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+// Spring constants for the track's slide animation — critically damped (damping = 2·√stiffness,
+// so it approaches the target with no overshoot/bounce, matching what sampling mobile.de's own
+// VDP gallery showed — see the spring loop's doc comment below) and tuned so a single ±1 move
+// settles in ~800-850ms, matching mobile.de's measured settle time for the same move.
+const SPRING_STIFFNESS = 64;
+const SPRING_DAMPING = 16;
+// Below these thresholds the spring is considered "arrived": stop stepping it (saves CPU while
+// idle instead of running a rAF loop forever) and snap the last fractional pixel so the resting
+// position is exact, not just "close enough". Both are small enough that the final snap is
+// sub-perceptible (0.015 of a slide's width is single-digit pixels at any real card size, at a
+// point where residual velocity is already crawling) — chosen by MEASURING actual settle time
+// live and tuning until it landed at mobile.de's own measured ~800-850ms, rather than picking
+// numbers that merely looked reasonable: 0.001/0.01 both measured over 1s to hit in practice
+// (VELOCITY decays slower than position for a critically damped spring, so it — not position —
+// ends up the binding constraint), well past the ~800ms the motion is already imperceptible.
+const SETTLE_POS_EPS = 0.015;
+const SETTLE_VEL_EPS = 0.09;
 
 export interface CardCarouselProps {
   /** ready-to-use image URLs (already resolved by the caller — no asset/window lookup here). */
@@ -34,7 +52,6 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   fit = 'cover',
   padded = true,
 }) => {
-  const [i, setI] = useState(0);
   const n = images.length;
   // MOBX-CQ-2: reset to the first slide whenever the caller hands us a
   // DIFFERENT gallery (this instance reused for another car) — otherwise a
@@ -44,17 +61,242 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   // every arrow click whose onChange triggered a parent re-render (the
   // counter advanced while the track snapped back to slide 0).
   const gallerySignature = images.join('|');
-  useEffect(() => {
-    setI(0);
+  // Loop-wrap (last→first / first→last): the flex row gets one extra CLONE slide at each
+  // end — clone of the LAST photo before the first, clone of the FIRST photo after the last
+  // — so a swipe/click past either edge keeps animating in the SAME direction into a
+  // real-looking next photo (mobile.de's own VDP gallery does the same) instead of jump-
+  // cutting or animating backward through every photo in between.
+  const extendedImages = n > 1 ? [images[n - 1], ...images, images[0]] : images;
+  // `trackIndex` (0..n+1, extended-array units; real slides live at 1..n) is the spring's
+  // TARGET and the only piece of animation state React itself renders from — used below to
+  // derive `i` (0..n-1, the "real" active slide for dots/onChange/the photo-count pill).
+  const [trackIndex, setTrackIndex] = useState(n > 1 ? 1 : 0);
+  // Mirrors `trackIndex`, updated SYNCHRONOUSLY inside go()/drag itself — not via React state,
+  // which only becomes readable to the NEXT interaction after a render has committed. Reading
+  // this (not the closured `trackIndex` state, and not a functional setState updater) is what
+  // makes go() correct no matter how soon after the last call it runs — see go()'s doc comment.
+  const trackIndexRef = useRef(trackIndex);
+  // The ANIMATED position, same 0..n+1 units as trackIndex but a continuous float — a ref, not
+  // state: the spring loop below writes it up to 60×/sec straight into the DOM via trackRef,
+  // never through React's render cycle (far too slow for smooth 60fps motion, and it would
+  // fight with the loop's own direct writes if React re-rendered the same style prop).
+  const visualPosRef = useRef(trackIndex);
+  const velocityRef = useRef(0);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const rafIdRef = useRef<number | null>(null);
+  // `n` read fresh inside the spring loop's closure would go stale if the gallery changes while
+  // a loop iteration is still in flight (a reused SRP card instance recycled mid-animation) —
+  // the gallery-reset effect below already forces a fresh start in that case, but mirroring `n`
+  // into a ref too costs nothing and removes the edge case outright.
+  const nRef = useRef(n);
+  nRef.current = n;
+
+  // Plain modulo, not clamped into [0, n+1] first: trackIndex is intentionally UNBOUNDED (see
+  // go()'s doc comment) — several rapid clicks can leave it well past a single clone-width
+  // before the spring loop's own rebase (below) has had a chance to catch up, and modulo maps
+  // ANY integer straight to the right real slide regardless, so `i`/the dots/the photo-count
+  // pill are correct the instant a click fires, never waiting on the animation to catch up.
+  const i = n > 1 ? (((trackIndex - 1) % n) + n) % n : 0;
+
+  const writeTransform = (pos: number) => {
+    const el = trackRef.current;
+    if (el) el.style.transform = `translateX(${(-pos * 100).toFixed(4)}%)`;
+  };
+
+  // The spring loop: steps visualPosRef toward trackIndexRef every frame via real spring-damper
+  // physics (F = -k·x - c·v), not a fixed-duration easing curve. That's the whole reason this
+  // component moved off a CSS transition: a CSS transition RESTARTS from zero velocity on every
+  // RETARGET (a new target set before the old transition finishes — arrows don't debounce, so
+  // this happens on anything faster than one click per ~800ms), and this curve's fast start
+  // meant every retarget produced a visible little "kick" of re-acceleration — read as jitter,
+  // a wrong-direction flicker, or an uneven stutter under fast repeat clicking (confirmed live:
+  // sampling the track's transform frame-by-frame during a burst of real clicks showed exactly
+  // this). A spring's velocity is a real, continuous state variable carried across retargets —
+  // clicking again before the previous move settles blends smoothly into the new target instead
+  // of restarting. This also matches mobile.de's own gallery: sampling ITS transform earlier
+  // showed a front-loaded, no-overshoot, ~800-900ms settle that a fixed-duration bezier curve
+  // could only approximate for an ISOLATED move — under retargeting a spring is what actually
+  // reproduces it, not just the single-move numbers.
+  const stepLoop = (lastT: number) => {
+    rafIdRef.current = requestAnimationFrame((now) => {
+      const dt = Math.min((now - lastT) / 1000, 1 / 30); // cap dt so a lag spike can't overshoot
+      const n2 = nRef.current;
+      const accel = SPRING_STIFFNESS * (trackIndexRef.current - visualPosRef.current) - SPRING_DAMPING * velocityRef.current;
+      velocityRef.current += accel * dt;
+      visualPosRef.current += velocityRef.current * dt;
+
+      // Loop-wrap rebase: whenever the ANIMATED position itself crosses a clone boundary,
+      // invisibly shift BOTH trackIndex and visualPos by ∓n into the matching REAL position —
+      // same photo either side, so each shift is imperceptible — keeping visualPos inside the
+      // single-clone-wide extended array this exact frame. Triggered by visualPos crossing 0 /
+      // n+1, NOT by trackIndex reaching them: trackIndex (the spring's TARGET) is intentionally
+      // UNBOUNDED — go() below no longer clamps it — so several clicks landing faster than the
+      // spring can visually catch up leave it arbitrarily far past a single clone-width. An
+      // earlier version rebased the moment the TARGET reached a boundary, shifting visualPos by
+      // the same ∓n regardless of where it actually was — correct ONLY if visualPos had already
+      // caught up to that boundary too; under a rapid-click burst it usually hadn't (confirmed
+      // live: sampling mid-burst caught visualPos at position ~2.9 of 4 getting yanked to ~-0.1
+      // by a rebase meant for position 4), producing exactly the kind of jarring cross-carousel
+      // jump this whole rewrite exists to eliminate. Rebasing on visualPos's own crossing avoids
+      // that by construction: it only ever fires within one frame's worth of motion of the
+      // boundary, however far past it trackIndex itself has drifted. A `while`, not `if`, so an
+      // extreme burst (or a large dt from a lag spike) rebases as many times in one frame as
+      // visualPos has actually crossed — real motion the array can only render one clone-width
+      // of at a time, not something to skip over in a single jump.
+      while (n2 > 1 && visualPosRef.current >= n2 + 1) {
+        trackIndexRef.current -= n2;
+        visualPosRef.current -= n2;
+        setTrackIndex(trackIndexRef.current);
+      }
+      while (n2 > 1 && visualPosRef.current <= 0) {
+        trackIndexRef.current += n2;
+        visualPosRef.current += n2;
+        setTrackIndex(trackIndexRef.current);
+      }
+
+      writeTransform(visualPosRef.current);
+
+      const atRest = Math.abs(trackIndexRef.current - visualPosRef.current) < SETTLE_POS_EPS && Math.abs(velocityRef.current) < SETTLE_VEL_EPS;
+      if (atRest) {
+        visualPosRef.current = trackIndexRef.current;
+        velocityRef.current = 0;
+        writeTransform(visualPosRef.current);
+        rafIdRef.current = null;
+        return;
+      }
+      stepLoop(now);
+    });
+  };
+  const ensureLoopRunning = () => {
+    if (rafIdRef.current == null) stepLoop(performance.now());
+  };
+  useEffect(
+    () => () => {
+      if (rafIdRef.current != null) cancelAnimationFrame(rafIdRef.current);
+    },
+    [],
+  );
+
+  // Gallery-swap reset — instant, no spring: jump straight to slide 0 with zero velocity so a
+  // reused instance (SRP list) never slides through a stale gallery's photos. useLayoutEffect
+  // (not useEffect) so the DOM is corrected before paint — no one-frame flash of the old
+  // position with the new gallery's images already swapped in underneath it.
+  useLayoutEffect(() => {
+    if (rafIdRef.current != null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    const start = n > 1 ? 1 : 0;
+    trackIndexRef.current = start;
+    visualPosRef.current = start;
+    velocityRef.current = 0;
+    setTrackIndex(start);
+    writeTransform(start);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [gallerySignature]);
-  const jump = (nx: number, e?: React.SyntheticEvent) => {
+  // Fires onChange whenever the DERIVED active slide actually changes — not on every
+  // trackIndex change, so the loop-wrap's snap-back (n+1→1 / 0→n, same photo either side)
+  // doesn't re-fire it. Reads onChange through a ref instead of listing it as a dependency:
+  // the VDP hands in a fresh inline arrow function every render, and depending on it directly
+  // would re-fire this effect (with the SAME `i`) on every unrelated parent re-render instead
+  // of only on an actual slide change.
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  const isFirstRender = useRef(true);
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+    onChangeRef.current && onChangeRef.current(i);
+  }, [i]);
+  // Every ±1 move goes through here, whether from a click or a released drag past the
+  // threshold. Reads/writes trackIndexRef synchronously (see its own doc comment above) so two
+  // calls landing back to back — realistic under fast repeat clicking — never race. Deliberately
+  // does NOT clamp/rebase trackIndex to stay within the single clone this component renders on
+  // either end — see the spring loop's rebase, which handles that (correctly: only once
+  // visualPos itself has actually caught up to a boundary, not the instant the discrete target
+  // passes one) — so several rapid clicks just keep pushing the target further out, and the
+  // spring keeps chasing it, rebasing its own coordinate system as needed along the way.
+  const go = (d: number, e?: React.SyntheticEvent) => {
+    if (n <= 1) return;
     e && e.stopPropagation();
-    setI(nx);
-    onChange && onChange(nx);
+    trackIndexRef.current += d;
+    setTrackIndex(trackIndexRef.current);
+    ensureLoopRunning();
+  };
+  // Pointer Events (not separate touch/mouse handlers) so mouse-drag on desktop works the exact
+  // same way touch-swipe already did — same pattern as VdpViewer's onStagePointer* handlers.
+  // Live-follow: visualPosRef tracks the pointer 1:1 while the gesture is in progress — same
+  // feel as mobile.de's / most gallery sliders' drag, instead of only reacting on release. The
+  // spring loop is paused for the duration (grabbing mid-flight kills any residual velocity —
+  // picking the track up should stop it dead, not have it keep drifting under your finger) and
+  // resumes on release, either toward a new target (go(), past the 40px threshold) or back to
+  // the unchanged one (springing back into place — also covers a plain click/tap, dx never
+  // moves, which still bubbles to the card as before since stopPropagation only happens in go()).
+  const dragRef = useRef<{ x: number; startPos: number } | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  // Set for one tick after a drag that crossed the 40px threshold — see onClick below for why.
+  const justSwipedRef = useRef(false);
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    if (n <= 1 || (e.target as HTMLElement).closest('button')) return;
+    dragRef.current = { x: e.clientX, startPos: visualPosRef.current };
+    velocityRef.current = 0;
+    if (rafIdRef.current != null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    setIsDragging(true);
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId);
+    } catch {
+      // same "nice to have" as VdpViewer's stage capture — safe to ignore if rejected.
+    }
+  };
+  const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = dragRef.current;
+    if (!start) return;
+    const width = e.currentTarget.clientWidth || 1;
+    visualPosRef.current = start.startPos - (e.clientX - start.x) / width;
+    writeTransform(visualPosRef.current);
+  };
+  const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    const start = dragRef.current;
+    dragRef.current = null;
+    setIsDragging(false);
+    if (!start) return;
+    const dx = e.clientX - start.x;
+    if (Math.abs(dx) > 40) {
+      justSwipedRef.current = true;
+      go(dx > 0 ? -1 : 1, e);
+    } else {
+      ensureLoopRunning(); // spring back to the unchanged trackIndex
+    }
+  };
+  const onPointerCancel = () => {
+    dragRef.current = null;
+    setIsDragging(false);
+    ensureLoopRunning();
+  };
+  // A completed drag/swipe (mousedown-move-up or touchstart-move-end, all on this same element)
+  // makes the browser fire a `click` right after pointerup REGARDLESS of how far the pointer
+  // moved in between — go()'s own e.stopPropagation() (called from onPointerUp, above) only
+  // stops THAT pointerup event; it can't reach forward to stop a separate click the browser
+  // hasn't dispatched yet. Left unguarded, that click still bubbles to a card this carousel
+  // lives inside (CarCard/CarRow wrap it in an onClick-to-navigate `<article>`) — swiping
+  // through a "similar cars" card's photos was navigating to that car's own page on release.
+  // Catching it here, one bubble-phase step before it would reach the card, and swallowing it
+  // ONLY when justSwipedRef says a real swipe (not a plain tap, which should still navigate —
+  // matches the click/tap-bubbles-through behavior noted in onPointerUp's own doc comment)
+  // just happened fixes it without the card needing to know anything about drag state itself.
+  const onClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (justSwipedRef.current) {
+      justSwipedRef.current = false;
+      e.stopPropagation();
+    }
   };
-  const go = (d: number, e?: React.SyntheticEvent) => jump((i + d + n) % n, e);
-  const trackRef = useRef<HTMLDivElement>(null);
-  const tx = useRef<number | null>(null);
 
   // 'auto' mode only diverges from plain 'contain' at desktop widths — below 601px it resolves
   // to 'contain' unconditionally, so mobile's existing rendering is untouched either way.
@@ -73,33 +315,53 @@ const CardCarousel: React.FunctionComponent<CardCarouselProps> = ({
   return (
     <div
       className="cardcar"
-      style={{ position: 'relative', height, overflow: 'hidden', borderRadius: radius }}
-      onTouchStart={(e) => {
-        tx.current = e.touches[0].clientX;
-      }}
-      onTouchEnd={(e) => {
-        if (tx.current == null) return;
-        const dx = e.changedTouches[0].clientX - tx.current;
-        tx.current = null;
-        if (Math.abs(dx) > 40) go(dx > 0 ? -1 : 1);
+      style={{
+        position: 'relative',
+        height,
+        overflow: 'hidden',
+        borderRadius: radius,
+        cursor: n > 1 ? (isDragging ? 'grabbing' : 'grab') : undefined,
+        // Without this, mobile browsers treat a horizontal touch-drag on this element as an
+        // ambiguous gesture and can hand it to their OWN native scroll/pan handling before our
+        // onPointerMove ever sees it (a pointercancel fires instead) — swipe-to-flip silently
+        // does nothing on a real touch device even though desktop mouse-drag (unaffected by
+        // touch-action) works fine. 'pan-y', not 'none': tells the browser only HORIZONTAL
+        // panning is ours to handle, so a mostly-vertical drag that starts on the photo still
+        // scrolls the page normally instead of getting swallowed. VdpViewer's full-screen stage
+        // already sets this (as `none` — no page scroll to preserve there); this was the one
+        // carousel surface that never got it.
+        touchAction: n > 1 ? 'pan-y' : undefined,
       }}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      onPointerCancel={onPointerCancel}
+      onClick={onClick}
     >
+      {/* transform is intentionally NOT part of this style object — it's owned entirely by
+          writeTransform() (the spring loop + drag handlers above), written straight to the DOM
+          node via trackRef. Letting React manage it here too, even with matching values, would
+          mean every trackIndex-driven re-render (a click, a rebase) re-applies React's own
+          understanding of the style — fighting the loop's per-frame writes for the same
+          property. The useLayoutEffect above sets the correct INITIAL value before first paint. */}
       <div
         ref={trackRef}
         style={{
           display: 'flex',
           height: '100%',
-          transform: `translateX(-${i * 100}%)`,
-          transition: 'transform var(--dur-3) var(--ease-emphasized)',
         }}
       >
-        {images.map((src, k) => (
+        {extendedImages.map((src, k) => (
           <img
             key={k}
             src={src}
             alt=""
             loading="lazy"
             decoding="async"
+            // otherwise the browser's own native image-drag (ghost preview + a dragstart
+            // that swallows the following pointer events) hijacks the gesture instead of
+            // our onPointerMove/onPointerUp swipe logic above.
+            draggable={false}
             style={
               autoDesktop
                 ? {