@sovereignfs/ui 0.45.0 → 0.83.1

package/src/components/SwipableMobileCarousel/SwipableMobileCarousel.tsx

@@ -0,0 +1,243 @@
+'use client';
+
+import {
+  Children,
+  isValidElement,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { useSnapCarousel } from '../../hooks/useSnapCarousel';
+import { SwipableMobileCarouselDots } from '../SwipableMobileCarouselDots/SwipableMobileCarouselDots';
+import { SwipableMobileCarouselSlide } from './SwipableMobileCarouselSlide';
+import { CarouselSlideMountContext } from './context';
+import styles from './SwipableMobileCarousel.module.css';
+
+export interface SwipableMobileCarouselIndicatorProps {
+  count: number;
+  activeIndex: number;
+  labels: (string | undefined)[];
+  onJump: (index: number) => void;
+}
+
+export interface SwipableMobileCarouselProps {
+  /** Controlled active slide index — the caller owns this (typically via
+   *  useCarouselRouteSync, or plain useState). */
+  activeIndex: number;
+  /** Called when a swipe gesture settles on a different index, or when the
+   *  reorder-jump fix re-snaps after the active slide's position changes.
+   *  The caller is responsible for updating `activeIndex` in response. */
+  onSettle: (index: number) => void;
+  /** How many slides on each side of the active one stay mounted. Default 1
+   *  matches both sovereign-tasks' and sovereign-shopper's existing "swipe
+   *  never shows a spinner" behavior. Slides outside this window keep their
+   *  DOM slot (so scroll-snap's position-based indexing stays correct) but
+   *  their children are not mounted at all. */
+  prefetchDistance?: number;
+  /** Passed straight through to the internal useSnapCarousel. */
+  settleDebounceMs?: number;
+  /** Required — labels the scroller region for assistive tech. No generic
+   *  fallback, since one would be wrong for every actual consumer. */
+  'aria-label': string;
+  /** Renders the indicator. Defaults to SwipableMobileCarouselDots. Pass
+   *  `null` to render no indicator at all. */
+  renderIndicator?: null | ((props: SwipableMobileCarouselIndicatorProps) => ReactNode);
+  className?: string;
+  /** Must be SwipableMobileCarouselSlide elements (nullish/boolean children
+   *  are safely skipped for conditional slides). A dev-mode warning is
+   *  logged for any other child type — see resolveSlides below. */
+  children: ReactNode;
+}
+
+interface ResolvedSlide {
+  key: string;
+  label: string | undefined;
+  element: ReactElement;
+}
+
+function describeChild(child: unknown): string {
+  if (isValidElement(child)) {
+    const type = child.type;
+    if (typeof type === 'string') return `<${type}>`;
+    if (typeof type === 'function') {
+      const named = type as { displayName?: string; name?: string };
+      return `<${named.displayName ?? named.name ?? 'Component'}>`;
+    }
+    return '<unknown>';
+  }
+  if (typeof child === 'string') return `string "${child}"`;
+  return String(child);
+}
+
+function resolveSlides(children: ReactNode): ResolvedSlide[] {
+  const slides: ResolvedSlide[] = [];
+  Children.forEach(children, (child, index) => {
+    if (child === null || child === undefined || child === false || child === true) return;
+    if (!isValidElement(child) || child.type !== SwipableMobileCarouselSlide) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          '[SwipableMobileCarousel] Every child must be a <SwipableMobileCarouselSlide>. ' +
+            `Found ${describeChild(child)} at position ${index}. A non-Slide child shifts every ` +
+            "subsequent slide's index, desyncing scroll-snap position from activeIndex.",
+        );
+      }
+      return;
+    }
+    const slideProps = child.props as { slideKey: string; label?: string };
+    if (process.env.NODE_ENV !== 'production' && !slideProps.label) {
+      console.warn(
+        `[SwipableMobileCarousel] SwipableMobileCarouselSlide "${slideProps.slideKey}" has no ` +
+          'label — it will show as "Slide N of count" in the default dots indicator.',
+      );
+    }
+    slides.push({ key: slideProps.slideKey, label: slideProps.label, element: child });
+  });
+  return slides;
+}
+
+/**
+ * SwipableMobileCarousel — a compound component for swiping between full-
+ * width slides (each an independent route/view on mobile), wrapping
+ * useSnapCarousel. This library's first compound component: every other
+ * component here is flat/prop-based, but slide content is large, arbitrary,
+ * per-plugin subtrees that need a header-known/body-loading split an
+ * array-of-objects prop would only express with worse JSX ergonomics.
+ *
+ * Owns rendering and mount-window mechanics only — it has no opinion on
+ * where slide data lives. Do NOT: (a) aggregate cross-slide data inside a
+ * SwipableMobileCarouselSlideBody (that recomputes on every slide render
+ * regardless of which slide is active — belongs in the parent, which
+ * already knows every slide exists); (b) mount a detail overlay (Sheet,
+ * Dialog) inside a Slide's children — mount it as a sibling of
+ * SwipableMobileCarousel instead, controlled by the same state that would
+ * otherwise drive a routed page's overlay. sovereign-tasks' current
+ * hand-rolled carousel does both and is measurably laggier than
+ * sovereign-shopper's equivalent, which keeps its overlay in the routed pane.
+ */
+export function SwipableMobileCarousel({
+  activeIndex,
+  onSettle,
+  prefetchDistance = 1,
+  settleDebounceMs = 120,
+  'aria-label': ariaLabel,
+  renderIndicator,
+  className,
+  children,
+}: SwipableMobileCarouselProps) {
+  const slides = useMemo(() => resolveSlides(children), [children]);
+  const count = slides.length;
+  const clampedActiveIndex = count === 0 ? 0 : Math.max(0, Math.min(count - 1, activeIndex));
+
+  // Initial scroll position, once — subsequent activeIndex changes come
+  // either from the user's own swipe (already reflected in DOM scroll
+  // position; re-syncing to the same index below is a harmless no-op) or an
+  // external navigation, which the effect below scrolls to explicitly.
+  const initialActiveIndexRef = useRef(clampedActiveIndex);
+
+  const { scrollRef, scrollToIndex, liveIndex } = useSnapCarousel({
+    itemCount: count,
+    onSettle,
+    debounceMs: settleDebounceMs,
+    initialIndex: initialActiveIndexRef.current,
+  });
+  useLayoutEffect(() => {
+    scrollToIndex(initialActiveIndexRef.current, 'instant');
+    // Runs once on mount only, matching both existing plugins' identical pattern.
+  }, []);
+
+  const didMountActiveIndexSyncRef = useRef(false);
+  useEffect(() => {
+    if (!didMountActiveIndexSyncRef.current) {
+      didMountActiveIndexSyncRef.current = true;
+      return;
+    }
+    scrollToIndex(clampedActiveIndex, 'smooth');
+  }, [clampedActiveIndex, scrollToIndex]);
+
+  // Reorder-jump fix: scroll-snap position tracks DOM order, not slide
+  // identity. If the previously-active slide's key still exists but moved
+  // (a caller re-sorted their slide array while mounted), re-snap to its
+  // new position and report it via onSettle so the caller's activeIndex
+  // stays in sync — otherwise scroll position silently desyncs from slide
+  // identity. Runs every commit (no dependency array) since it needs to
+  // notice any children change, not just a specific prop.
+  const prevKeysRef = useRef<string[] | null>(null);
+  useLayoutEffect(() => {
+    const currentKeys = slides.map((s) => s.key);
+    const prevKeys = prevKeysRef.current;
+    if (prevKeys) {
+      const sameOrder =
+        prevKeys.length === currentKeys.length && prevKeys.every((k, i) => k === currentKeys[i]);
+      if (!sameOrder) {
+        const activeKey = prevKeys[clampedActiveIndex];
+        if (activeKey !== undefined) {
+          const newIndex = currentKeys.indexOf(activeKey);
+          if (newIndex !== -1 && newIndex !== clampedActiveIndex) {
+            scrollToIndex(newIndex, 'instant');
+            onSettle(newIndex);
+          }
+        }
+      }
+    }
+    prevKeysRef.current = currentKeys;
+  });
+
+  function handleJump(index: number) {
+    // scrollToIndex sets useSnapCarousel's own dedupe ref synchronously, so
+    // the natural scroll-settle detection will NOT re-report this index —
+    // onSettle must be called directly here, same pairing as the
+    // reorder-jump fix above.
+    scrollToIndex(index, 'smooth');
+    onSettle(index);
+  }
+
+  const labels = slides.map((s) => s.label);
+  const indicator =
+    renderIndicator === null ? null : renderIndicator ? (
+      renderIndicator({ count, activeIndex: clampedActiveIndex, labels, onJump: handleJump })
+    ) : (
+      <SwipableMobileCarouselDots
+        count={count}
+        activeIndex={clampedActiveIndex}
+        labels={labels}
+        aria-label={ariaLabel}
+        onJump={handleJump}
+      />
+    );
+
+  return (
+    <div className={[styles.wrap, className].filter(Boolean).join(' ')}>
+      <div className={styles.scroller} ref={scrollRef} role="region" aria-label={ariaLabel}>
+        {slides.map((slide, i) => (
+          <div className={styles.slide} key={slide.key}>
+            <CarouselSlideMountContext.Provider
+              value={{
+                // Union of the settled index and the live (real-time,
+                // pre-settle) scroll position — see useSnapCarousel's own
+                // liveIndex doc comment. A single fast flick can carry
+                // native scroll-snap momentum past an intermediate slide to
+                // one two-or-more away before settle-detection's debounce
+                // window ever reports it; without also checking liveIndex,
+                // the slide the container had already visually scrolled to
+                // stays unmounted (rendering nothing at all, not even a
+                // loading skeleton) for that entire window.
+                isMounted:
+                  Math.abs(i - clampedActiveIndex) <= prefetchDistance ||
+                  Math.abs(i - liveIndex) <= prefetchDistance,
+              }}
+            >
+              {slide.element}
+            </CarouselSlideMountContext.Provider>
+          </div>
+        ))}
+      </div>
+      {/* Positioning (overlay the bottom of .wrap) lives here, applied around
+          whatever renderIndicator returns — see .indicatorSlot's own doc
+          comment for why this can't be delegated to the indicator itself. */}
+      {indicator && <div className={styles.indicatorSlot}>{indicator}</div>}
+    </div>
+  );
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlide.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { useContext, type ReactNode } from 'react';
+import { CarouselSlideMountContext } from './context';
+
+export interface SwipableMobileCarouselSlideProps {
+  /** Stable identity for this slide, independent of its position among
+   *  siblings — required. This is what makes SwipableMobileCarousel's
+   *  reorder-jump fix possible: a plain array index can't distinguish "this
+   *  slide moved to position 2" from "this slide was removed and a
+   *  different one is now at position 2." Reuse whatever id the caller
+   *  already keys their `.map()` on (e.g. a list's own id). */
+  slideKey: string;
+  /** Accessible label surfaced to the default dots indicator (e.g.
+   *  "Groceries"). Falls back to "Slide N of count" if omitted — omitting it
+   *  logs a dev-mode warning, since every real slide usually has a title
+   *  available synchronously already. */
+  label?: string;
+  /** SwipableMobileCarouselSlideHeader/Body/Footer, in any order/subset. */
+  children: ReactNode;
+}
+
+/**
+ * SwipableMobileCarouselSlide — a single slide of a SwipableMobileCarousel.
+ * Renders its children only while within the carousel's mount window (the
+ * active slide ± its configured prefetchDistance); outside that window it
+ * renders nothing, matching both sovereign-tasks and sovereign-shopper's
+ * existing "never fetch/render a non-neighbor slide" behavior, now
+ * centralized instead of hand-rolled per plugin.
+ */
+export function SwipableMobileCarouselSlide({ children }: SwipableMobileCarouselSlideProps) {
+  const ctx = useContext(CarouselSlideMountContext);
+  if (!ctx?.isMounted) return null;
+  return <>{children}</>;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideBodyProps {
+  children: ReactNode;
+  /** While true, renders `loadingFallback` INSTEAD OF children — scoped to
+   *  just this region, not the whole slide. This is what fixes the
+   *  "whole slide blanks out, title included, until its own fetch resolves"
+   *  bug: a caller renders `<SwipableMobileCarouselSlideHeader>` from
+   *  already-known metadata unconditionally, and gates only this component's
+   *  `loading` on the slower fetch — the natural way to compose
+   *  Header/Body/Footer as siblings already produces that behavior, instead
+   *  of gating the entire slide behind one boolean. */
+  loading?: boolean;
+  loadingFallback?: ReactNode;
+  className?: string;
+}
+
+const defaultLoadingFallback = <div className={styles.loading}>Loading…</div>;
+
+/**
+ * SwipableMobileCarouselSlideBody — the scrollable region of a slide.
+ *
+ * Deliberately does not set `touch-action: pan-y` on its scroll container
+ * (see SwipableMobileCarouselSlideParts.module.css's `.body` rule) — that
+ * would intersect-to-empty against the carousel's own horizontal
+ * touch-action handling (docs/architecture-rules.md's touch-action
+ * intersection rule), breaking both the vertical scroll here and the
+ * horizontal swipe between slides.
+ */
+export function SwipableMobileCarouselSlideBody({
+  children,
+  loading = false,
+  loadingFallback,
+  className,
+}: SwipableMobileCarouselSlideBodyProps) {
+  return (
+    <div className={[styles.body, className].filter(Boolean).join(' ')}>
+      {loading ? (loadingFallback ?? defaultLoadingFallback) : children}
+    </div>
+  );
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideFooterProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * SwipableMobileCarouselSlideFooter — always renders its children, no
+ * loading concept. See SwipableMobileCarouselSlideHeader's doc comment.
+ */
+export function SwipableMobileCarouselSlideFooter({
+  children,
+  className,
+}: SwipableMobileCarouselSlideFooterProps) {
+  return <div className={[styles.footer, className].filter(Boolean).join(' ')}>{children}</div>;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import styles from './SwipableMobileCarouselSlideParts.module.css';
+
+export interface SwipableMobileCarouselSlideHeaderProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * SwipableMobileCarouselSlideHeader — always renders its children, no
+ * loading concept. Meant for content already known synchronously (a list's
+ * title, color, item count from data the caller already has) so it can
+ * render immediately even while SwipableMobileCarouselSlideBody's own
+ * content is still loading — see that component's doc comment.
+ */
+export function SwipableMobileCarouselSlideHeader({
+  children,
+  className,
+}: SwipableMobileCarouselSlideHeaderProps) {
+  return <div className={[styles.header, className].filter(Boolean).join(' ')}>{children}</div>;
+}

package/src/components/SwipableMobileCarousel/SwipableMobileCarouselSlideParts.module.css

@@ -0,0 +1,29 @@
+.header,
+.footer {
+  flex: 0 0 auto;
+}
+
+.body {
+  flex: 1 1 auto;
+  min-height: 0; /* allow shrinking inside the slide's flex column, so it can scroll instead of overflowing */
+  overflow-y: auto;
+  overflow-x: hidden;
+  /* Deliberately does NOT set touch-action: pan-y here. touch-action's
+     effective value is the INTERSECTION of this element's and every
+     ancestor's value (docs/architecture-rules.md) — the ancestor .scroller
+     (SwipableMobileCarousel.module.css) needs the horizontal swipe gesture,
+     so pan-y here ∩ that horizontal handling would resolve to neither axis
+     working natively. Relying on the browser's default touch-action (auto)
+     here lets native gesture arbitration between the two nested scrollers
+     sort out which axis wins per-gesture — don't "fix" perceived nested-
+     scroll jank by adding pan-y; it silently breaks horizontal swipe instead. */
+}
+
+.loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: var(--sv-color-text-subtle);
+  font-size: var(--sv-font-size-sm);
+}

package/src/components/SwipableMobileCarousel/__tests__/SwipableMobileCarousel.test.tsx

@@ -0,0 +1,214 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { SwipableMobileCarousel } from '../SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../SwipableMobileCarouselSlide';
+import { SwipableMobileCarouselSlideHeader } from '../SwipableMobileCarouselSlideHeader';
+import { SwipableMobileCarouselSlideBody } from '../SwipableMobileCarouselSlideBody';
+
+// Same jsdom scroll polyfill/fake-timer setup as useSnapCarousel.test.tsx,
+// since this component wraps that hook directly.
+beforeEach(() => {
+  vi.useFakeTimers();
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  vi.runOnlyPendingTimers();
+  vi.useRealTimers();
+  cleanup();
+});
+
+function setLayout(el: HTMLElement, clientWidth: number, scrollLeft: number) {
+  Object.defineProperty(el, 'clientWidth', { value: clientWidth, configurable: true });
+  Object.defineProperty(el, 'scrollLeft', { value: scrollLeft, configurable: true });
+}
+
+const KEYS = ['a', 'b', 'c', 'd', 'e'];
+
+function FiveSlides({
+  activeIndex,
+  onSettle,
+}: {
+  activeIndex: number;
+  onSettle: (i: number) => void;
+}) {
+  return (
+    <SwipableMobileCarousel activeIndex={activeIndex} onSettle={onSettle} aria-label="Test slides">
+      {KEYS.map((key) => (
+        <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+          <SwipableMobileCarouselSlideHeader>{`header-${key}`}</SwipableMobileCarouselSlideHeader>
+          <SwipableMobileCarouselSlideBody>{`body-${key}`}</SwipableMobileCarouselSlideBody>
+        </SwipableMobileCarouselSlide>
+      ))}
+    </SwipableMobileCarousel>
+  );
+}
+
+describe('SwipableMobileCarousel', () => {
+  it('only mounts the active slide and its immediate neighbors (default prefetchDistance=1)', () => {
+    render(<FiveSlides activeIndex={2} onSettle={() => {}} />);
+    // active (c) and neighbors (b, d) are mounted
+    expect(screen.getByText('header-b')).toBeDefined();
+    expect(screen.getByText('header-c')).toBeDefined();
+    expect(screen.getByText('header-d')).toBeDefined();
+    // out-of-window slides (a, e) render nothing at all
+    expect(screen.queryByText('header-a')).toBeNull();
+    expect(screen.queryByText('body-a')).toBeNull();
+    expect(screen.queryByText('header-e')).toBeNull();
+    expect(screen.queryByText('body-e')).toBeNull();
+  });
+
+  it("SlideBody's loading prop only hides that region, not the Header", () => {
+    render(
+      <SwipableMobileCarousel activeIndex={0} onSettle={() => {}} aria-label="Test slides">
+        <SwipableMobileCarouselSlide slideKey="only" label="Only">
+          <SwipableMobileCarouselSlideHeader>the-title</SwipableMobileCarouselSlideHeader>
+          <SwipableMobileCarouselSlideBody loading>tasks-content</SwipableMobileCarouselSlideBody>
+        </SwipableMobileCarouselSlide>
+      </SwipableMobileCarousel>,
+    );
+    expect(screen.getByText('the-title')).toBeDefined();
+    expect(screen.queryByText('tasks-content')).toBeNull();
+    expect(screen.getByText('Loading…')).toBeDefined();
+  });
+
+  it('calls onSettle with the new index after a swipe settles', () => {
+    const onSettle = vi.fn();
+    render(<FiveSlides activeIndex={0} onSettle={onSettle} />);
+    const scroller = screen.getByRole('region', { name: 'Test slides' });
+    fireEvent.touchStart(scroller);
+    setLayout(scroller, 300, 300); // scrollLeft 300 / width 300 -> index 1
+    fireEvent.scroll(scroller);
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(1);
+  });
+
+  it('clicking a dot calls onSettle directly with that index', () => {
+    const onSettle = vi.fn();
+    render(<FiveSlides activeIndex={0} onSettle={onSettle} />);
+    const dots = screen.getAllByRole('tab');
+    const fourthDot = dots[3];
+    if (!fourthDot) throw new Error('expected a 4th dot');
+    setLayout(screen.getByRole('region', { name: 'Test slides' }), 300, 0);
+    fireEvent.click(fourthDot);
+    expect(onSettle).toHaveBeenCalledWith(3);
+  });
+
+  it('positions both the default and a custom renderIndicator inside the same overlay slot', () => {
+    // Regression test: the overlay-positioning class used to be applied
+    // directly to the default SwipableMobileCarouselDots instance, so any
+    // caller-supplied renderIndicator rendered as a plain static element
+    // instead — pushed out of view below the full-height scroller. The
+    // carousel must own positioning for whatever renderIndicator returns.
+    const { unmount } = render(<FiveSlides activeIndex={0} onSettle={() => {}} />);
+    const defaultTablist = screen.getByRole('tablist');
+    expect(defaultTablist.parentElement?.className).toMatch(/indicatorSlot/);
+    unmount();
+
+    render(
+      <SwipableMobileCarousel
+        activeIndex={0}
+        onSettle={() => {}}
+        aria-label="Test slides"
+        renderIndicator={({ count, activeIndex, onJump }) => (
+          <div role="tablist" aria-label="Custom">
+            {Array.from({ length: count }, (_, i) => (
+              <button key={i} type="button" role="tab" onClick={() => onJump(i)}>
+                {i === activeIndex ? 'active' : 'inactive'}
+              </button>
+            ))}
+          </div>
+        )}
+      >
+        {KEYS.map((key) => (
+          <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+            {`slide-${key}`}
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>,
+    );
+    const customTablist = screen.getByRole('tablist', { name: 'Custom' });
+    expect(customTablist.parentElement?.className).toMatch(/indicatorSlot/);
+  });
+
+  it('re-snaps and reports the new index when the active slide moves position (reorder-jump fix)', () => {
+    function Reorderable({ order, onSettle }: { order: string[]; onSettle: (i: number) => void }) {
+      return (
+        <SwipableMobileCarousel activeIndex={1} onSettle={onSettle} aria-label="Test slides">
+          {order.map((key) => (
+            <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+              <SwipableMobileCarouselSlideHeader>{`header-${key}`}</SwipableMobileCarouselSlideHeader>
+            </SwipableMobileCarouselSlide>
+          ))}
+        </SwipableMobileCarousel>
+      );
+    }
+    const onSettle = vi.fn();
+    const { rerender } = render(<Reorderable order={['a', 'b', 'c']} onSettle={onSettle} />);
+    const scroller = screen.getByRole('region', { name: 'Test slides' });
+    setLayout(scroller, 300, 0);
+    const spy = vi.spyOn(scroller, 'scrollTo');
+
+    // 'b' (index 1, active) moves to index 0.
+    rerender(<Reorderable order={['b', 'a', 'c']} onSettle={onSettle} />);
+
+    expect(onSettle).toHaveBeenCalledWith(0);
+    expect(spy).toHaveBeenCalledWith({ left: 0, behavior: 'instant' });
+  });
+
+  it('mounts a slide reached by a fast multi-slide flick before settle-detection reports it', () => {
+    // Regression test, found via a user screen recording: a fast flick can
+    // carry native scroll-snap momentum straight past an intermediate slide
+    // to one two-or-more away in a single continuous gesture. Settle-
+    // detection deliberately still waits out the full debounce window before
+    // calling onSettle (to distinguish a real settle from drift — see
+    // useSnapCarousel's chainTrustedRef comment), but the mount window used
+    // to be keyed *only* off that settled index — so the slide the container
+    // had already scrolled to, visually, sat completely unmounted (not even
+    // a loading skeleton, per SwipableMobileCarouselSlide's `return null`)
+    // for the entire debounce window. liveIndex closes that gap.
+    const onSettle = vi.fn();
+    const KEYS8 = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
+    function EightSlides({ onSettle }: { onSettle: (i: number) => void }) {
+      return (
+        <SwipableMobileCarousel activeIndex={0} onSettle={onSettle} aria-label="Test slides">
+          {KEYS8.map((key) => (
+            <SwipableMobileCarouselSlide key={key} slideKey={key} label={key}>
+              <SwipableMobileCarouselSlideHeader>{`header-${key}`}</SwipableMobileCarouselSlideHeader>
+            </SwipableMobileCarouselSlide>
+          ))}
+        </SwipableMobileCarousel>
+      );
+    }
+    render(<EightSlides onSettle={onSettle} />);
+    const scroller = screen.getByRole('region', { name: 'Test slides' });
+    // Slide 'e' (index 4) is well outside the default prefetchDistance=1
+    // window around the settled index 0.
+    expect(screen.queryByText('header-e')).toBeNull();
+
+    fireEvent.touchStart(scroller);
+    setLayout(scroller, 300, 1200); // scrollLeft 1200 / width 300 -> index 4
+    fireEvent.scroll(scroller);
+    // Well short of the 120ms settle debounce — onSettle must not have fired
+    // yet, but the rAF-throttled liveIndex update has had time to run.
+    act(() => void vi.advanceTimersByTime(20));
+    expect(onSettle).not.toHaveBeenCalled();
+    expect(screen.getByText('header-e')).toBeDefined();
+
+    act(() => void vi.advanceTimersByTime(120));
+    expect(onSettle).toHaveBeenCalledWith(4);
+  });
+
+  it('does not re-snap when slide order is unchanged', () => {
+    function Reorderable({ onSettle }: { onSettle: (i: number) => void }) {
+      return <FiveSlides activeIndex={2} onSettle={onSettle} />;
+    }
+    const onSettle = vi.fn();
+    const { rerender } = render(<Reorderable onSettle={onSettle} />);
+    rerender(<Reorderable onSettle={onSettle} />);
+    expect(onSettle).not.toHaveBeenCalled();
+  });
+});

package/src/components/SwipableMobileCarousel/__tests__/SwipableMobileCarouselDevGuard.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { SwipableMobileCarousel } from '../SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../SwipableMobileCarouselSlide';
+
+beforeEach(() => {
+  if (!Element.prototype.scrollTo) {
+    Element.prototype.scrollTo = vi.fn();
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function renderWithStrayChild() {
+  return render(
+    <SwipableMobileCarousel activeIndex={0} onSettle={() => {}} aria-label="Test slides">
+      <SwipableMobileCarouselSlide slideKey="a" label="A">
+        content
+      </SwipableMobileCarouselSlide>
+      {/* stray non-Slide child — shifts index math for anything after it */}
+      <div>oops</div>
+      <SwipableMobileCarouselSlide slideKey="b" label="B">
+        content
+      </SwipableMobileCarouselSlide>
+    </SwipableMobileCarousel>,
+  );
+}
+
+describe('SwipableMobileCarousel dev-mode child-type guard', () => {
+  it('warns via console.error in development, mentioning the offending child', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'development');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('<div>'));
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+
+  it('does not call console.error in production', () => {
+    const originalEnv = process.env.NODE_ENV;
+    vi.stubEnv('NODE_ENV', 'production');
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    expect(() => renderWithStrayChild()).not.toThrow();
+
+    expect(errorSpy).not.toHaveBeenCalled();
+    vi.stubEnv('NODE_ENV', originalEnv ?? 'test');
+  });
+
+  it('never throws, even with a stray child (a miscounted slide degrades, it does not crash)', () => {
+    vi.stubEnv('NODE_ENV', 'development');
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => renderWithStrayChild()).not.toThrow();
+  });
+});