@sovereignfs/ui 0.54.0 → 0.83.1

package/src/components/SwipableMobileCarousel/SwipableMobileCarousel.tsx

@@ -131,17 +131,18 @@ export function SwipableMobileCarousel({
   const count = slides.length;
   const clampedActiveIndex = count === 0 ? 0 : Math.max(0, Math.min(count - 1, activeIndex));
 
-  const { scrollRef, scrollToIndex } = useSnapCarousel({
-    itemCount: count,
-    onSettle,
-    debounceMs: settleDebounceMs,
-  });
-
   // 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.
@@ -199,7 +200,6 @@ export function SwipableMobileCarousel({
       renderIndicator({ count, activeIndex: clampedActiveIndex, labels, onJump: handleJump })
     ) : (
       <SwipableMobileCarouselDots
-        className={styles.dots}
         count={count}
         activeIndex={clampedActiveIndex}
         labels={labels}
@@ -214,14 +214,30 @@ export function SwipableMobileCarousel({
         {slides.map((slide, i) => (
           <div className={styles.slide} key={slide.key}>
             <CarouselSlideMountContext.Provider
-              value={{ isMounted: Math.abs(i - clampedActiveIndex) <= prefetchDistance }}
+              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>
-      {indicator}
+      {/* 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/__tests__/SwipableMobileCarousel.test.tsx

@@ -79,6 +79,7 @@ describe('SwipableMobileCarousel', () => {
     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));
@@ -96,6 +97,43 @@ describe('SwipableMobileCarousel', () => {
     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 (
@@ -121,6 +159,49 @@ describe('SwipableMobileCarousel', () => {
     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} />;

package/src/components/SwipableMobileCarouselDots/SwipableMobileCarouselDots.module.css

@@ -5,6 +5,21 @@
   gap: var(--sv-space-2);
 }
 
+/* Opt-in — see the `density` prop doc comment. Shrinks both the gap and each
+   dot's own hit target (20px -> 16px) — for a carousel with enough slides
+   that even the space-1 gap alone still read as too wide. The visible 6px
+   dot is unchanged; only the surrounding tap-target box shrinks, via the
+   descendant override below rather than a second dot variant, so this stays
+   a pure CSS opt-in with no JS/prop plumbing beyond `density` itself. */
+.dotsCompact {
+  gap: var(--sv-space-1);
+}
+
+.dotsCompact .dot {
+  width: 16px;
+  height: 16px;
+}
+
 .dot {
   /* A 6px visible dot is too small a hit target on its own — the button's
      real box is larger (20px) with the dot itself painted by ::before and

package/src/components/SwipableMobileCarouselDots/SwipableMobileCarouselDots.tsx

@@ -12,6 +12,14 @@ export interface SwipableMobileCarouselDotsProps {
   /** Labels the whole group — required, no generic fallback (mirrors
    *  SwipableMobileCarousel's own required aria-label). */
   'aria-label': string;
+  /** `'compact'` halves the gap between dots (`--sv-space-2` → `--sv-space-1`)
+   *  and shrinks each dot's own hit target (20px → 16px) — for a carousel
+   *  with enough slides that even the reduced gap alone still reads as too
+   *  wide on a narrow viewport (e.g. a many-list mobile app). The visible
+   *  6px dot itself is unchanged; only its surrounding tap-target box
+   *  shrinks. Defaults to `'default'` — every existing consumer's spacing is
+   *  unaffected unless it opts in. */
+  density?: 'default' | 'compact';
   className?: string;
 }
 
@@ -34,13 +42,16 @@ export function SwipableMobileCarouselDots({
   onJump,
   labels,
   'aria-label': ariaLabel,
+  density = 'default',
   className,
 }: SwipableMobileCarouselDotsProps) {
   return (
     <div
       role="tablist"
       aria-label={ariaLabel}
-      className={[styles.dots, className].filter(Boolean).join(' ')}
+      className={[styles.dots, density === 'compact' ? styles.dotsCompact : '', className]
+        .filter(Boolean)
+        .join(' ')}
     >
       {Array.from({ length: count }, (_, i) => {
         const active = i === activeIndex;

package/src/components/SwipeStack/SwipeStack.module.css

@@ -0,0 +1,101 @@
+.wrap {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-3);
+  height: 100%;
+  width: 100%;
+}
+
+.stack {
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.peek {
+  position: absolute;
+  inset: 0;
+  transform: scale(0.94) translateY(var(--sv-space-3));
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.cardSlot {
+  position: absolute;
+  inset: 0;
+}
+
+/* Styled directly rather than wrapping the Card component: Card doesn't
+   forward a ref, and this element must be the exact node useSwipeStack
+   translates/rotates as one unit — a Card wrapping an inner dragged div
+   would leave its own border/shadow visually static while only the inner
+   div moved. */
+.card {
+  position: relative;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+  background: var(--sv-color-surface-raised);
+  border: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  border-radius: var(--sv-radius-lg);
+  box-shadow: var(--sv-shadow-card);
+  touch-action: none; /* always overridden inline with useSwipeStack's computed value */
+  user-select: none;
+  cursor: grab;
+}
+
+.card:active {
+  cursor: grabbing;
+}
+
+.stamp {
+  position: absolute;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  padding: var(--sv-space-1) var(--sv-space-3);
+  border: 2px solid var(--sv-color-text-primary);
+  border-radius: var(--sv-radius-md);
+  background: var(--sv-color-surface-raised);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  pointer-events: none;
+}
+
+.stampUp {
+  top: var(--sv-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: var(--sv-stack-progress-up, 0);
+}
+
+.stampDown {
+  bottom: var(--sv-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: var(--sv-stack-progress-down, 0);
+}
+
+.stampLeft {
+  top: var(--sv-space-4);
+  left: var(--sv-space-4);
+  transform: rotate(-8deg);
+  opacity: var(--sv-stack-progress-left, 0);
+}
+
+.stampRight {
+  top: var(--sv-space-4);
+  right: var(--sv-space-4);
+  transform: rotate(8deg);
+  opacity: var(--sv-stack-progress-right, 0);
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+  gap: var(--sv-space-2);
+  flex: 0 0 auto;
+}

package/src/components/SwipeStack/SwipeStack.tsx

@@ -0,0 +1,199 @@
+'use client';
+
+import { Children, isValidElement, useEffect, useRef, useState } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { Button } from '../Button/Button';
+import { Icon, type IconName } from '../Icon/Icon';
+import { useSwipeStack, SWIPE_STACK_TRANSITION_MS } from '../../hooks/useSwipeStack';
+import type { SwipeDirection } from '../../hooks/useSwipeStack';
+import { SwipeStackCard } from './SwipeStackCard';
+import styles from './SwipeStack.module.css';
+
+export interface SwipeDirectionMeta {
+  /** Visible text on the fallback button and the in-drag stamp. */
+  label: string;
+  icon?: IconName;
+}
+
+export interface SwipeStackProps {
+  /** Required — labels the swipeable region for assistive tech. No generic
+   *  fallback, since one would be wrong for every actual consumer. */
+  'aria-label': string;
+  /** Which of the 4 directions are live, and what each is called. A
+   *  direction absent here cannot be dragged toward at all (useSwipeStack
+   *  treats it as a wall) and gets no fallback button or stamp. SwipeStack
+   *  itself has no opinion on what a direction *means* — that vocabulary
+   *  belongs entirely to the caller. */
+  directions: Partial<Record<SwipeDirection, SwipeDirectionMeta>>;
+  /** Fires once a drag (or a fallback button) commits to a direction. Every
+   *  configured direction behaves the same way: the card leaves for good —
+   *  there is no reversible "go back" state. SwipeStack has no opinion on
+   *  where card data lives; the caller is responsible for eventually no
+   *  longer including this cardId in children (e.g. once a mutation lands). */
+  onSwipe: (direction: SwipeDirection, cardId: string) => void;
+  /** Effective drag distance (px) required to commit. Passed straight
+   *  through to useSwipeStack. */
+  threshold?: number;
+  className?: string;
+  /** Must be SwipeStackCard elements (nullish/boolean children are safely
+   *  skipped for conditional cards). A dev-mode warning is logged for any
+   *  other child type — see resolveCards below. */
+  children: ReactNode;
+}
+
+interface ResolvedCard {
+  key: string;
+  element: ReactElement;
+}
+
+const DIRECTION_KEYS: readonly SwipeDirection[] = ['up', 'down', 'left', 'right'];
+
+const STAMP_CLASS: Record<SwipeDirection, string> = {
+  up: styles.stampUp as string,
+  down: styles.stampDown as string,
+  left: styles.stampLeft as string,
+  right: styles.stampRight as string,
+};
+
+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 resolveCards(children: ReactNode): ResolvedCard[] {
+  const cards: ResolvedCard[] = [];
+  Children.forEach(children, (child, index) => {
+    if (child === null || child === undefined || child === false || child === true) return;
+    if (!isValidElement(child) || child.type !== SwipeStackCard) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.error(
+          '[SwipeStack] Every child must be a <SwipeStackCard>. ' +
+            `Found ${describeChild(child)} at position ${index}.`,
+        );
+      }
+      return;
+    }
+    const cardProps = child.props as { cardId: string };
+    cards.push({ key: cardProps.cardId, element: child });
+  });
+  return cards;
+}
+
+/**
+ * SwipeStack — a compound component for triaging one card at a time by
+ * dragging it left/right/up/down (wrapping useSwipeStack), plus an
+ * always-visible non-gesture fallback: a button per configured direction,
+ * wired to the identical commit path and exit animation as a real drag.
+ *
+ * Every direction is independently optional and behaves the same way once
+ * triggered — the card leaves for good, there is no reversible "go back".
+ * SwipeStack owns rendering, drag physics, and the stamp/fallback UI only;
+ * it has no opinion on where card data lives or what a direction means —
+ * see SwipeStackProps.onSwipe.
+ */
+export function SwipeStack({
+  'aria-label': ariaLabel,
+  directions,
+  onSwipe,
+  threshold,
+  className,
+  children,
+}: SwipeStackProps) {
+  const cards = resolveCards(children);
+  const [dismissed, setDismissed] = useState<ReadonlySet<string>>(() => new Set());
+  const [exiting, setExiting] = useState<ResolvedCard | null>(null);
+  const exitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (exitTimerRef.current) clearTimeout(exitTimerRef.current);
+    },
+    [],
+  );
+
+  const available = cards.filter((c) => !dismissed.has(c.key));
+  const nextUp = available[0];
+  const current = exiting ?? nextUp ?? null;
+  const peek = exiting ? nextUp : available[1];
+
+  const liveDirections = DIRECTION_KEYS.filter((d) => directions[d]);
+
+  const { cardRef, wrapRef, handlers, touchAction, triggerCommit } = useSwipeStack({
+    directions: liveDirections,
+    threshold,
+    disabled: !!exiting || !nextUp,
+    onCommit(direction) {
+      const committed = current;
+      if (!committed) return;
+      setDismissed((prev) => new Set(prev).add(committed.key));
+      setExiting(committed);
+      if (exitTimerRef.current) clearTimeout(exitTimerRef.current);
+      exitTimerRef.current = setTimeout(() => {
+        setExiting((prev) => (prev?.key === committed.key ? null : prev));
+      }, SWIPE_STACK_TRANSITION_MS);
+      onSwipe(direction, committed.key);
+    },
+  });
+
+  return (
+    <div className={[styles.wrap, className].filter(Boolean).join(' ')}>
+      <div className={styles.stack} role="region" aria-label={ariaLabel}>
+        {peek && (
+          <div className={styles.peek} key={peek.key} aria-hidden="true">
+            {peek.element}
+          </div>
+        )}
+        {current && (
+          <div className={styles.cardSlot} key={current.key} ref={wrapRef}>
+            {liveDirections.map((d) => {
+              const meta = directions[d];
+              if (!meta) return null;
+              return (
+                <div
+                  key={d}
+                  className={[styles.stamp, STAMP_CLASS[d]].join(' ')}
+                  aria-hidden="true"
+                >
+                  {meta.icon && <Icon name={meta.icon} size="sm" aria-hidden />}
+                  <span>{meta.label}</span>
+                </div>
+              );
+            })}
+            <div className={styles.card} ref={cardRef} style={{ touchAction }} {...handlers}>
+              {current.element}
+            </div>
+          </div>
+        )}
+      </div>
+      {liveDirections.length > 0 && (
+        <div className={styles.actions} role="group" aria-label={`${ariaLabel} actions`}>
+          {liveDirections.map((d) => {
+            const meta = directions[d];
+            if (!meta) return null;
+            return (
+              <Button
+                key={d}
+                variant="secondary"
+                size="sm"
+                disabled={!current}
+                onClick={() => triggerCommit(d)}
+              >
+                {meta.icon && <Icon name={meta.icon} size="sm" aria-hidden />}
+                {meta.label}
+              </Button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/SwipeStack/SwipeStackCard.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+
+export interface SwipeStackCardProps {
+  /** Stable identity for this card, independent of its position among
+   *  siblings — required. This is what SwipeStack reads (via child.props,
+   *  not React's own `key`, which a component can't see on itself) to know
+   *  which card is on top and what id to report through onSwipe. Reuse
+   *  whatever id the caller already keys their `.map()` on. */
+  cardId: string;
+  children: ReactNode;
+}
+
+/**
+ * SwipeStackCard — a single card of a SwipeStack. Unlike
+ * SwipableMobileCarouselSlide, this has no mount-window logic of its own:
+ * SwipeStack only ever renders the top two cards' elements at all (there is
+ * no scroll-position reason to keep every sibling in the DOM the way the
+ * carousel's scroll-snap track does), so there is nothing here to gate.
+ */
+export function SwipeStackCard({ children }: SwipeStackCardProps) {
+  return <>{children}</>;
+}