Percent Slide Carousel

'use client';

import {
  Children,
  isValidElement,
  useCallback,
  useState,
  type ReactNode,
} from 'react';
import { clamp } from '@/lib/damp';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { wrapIndex } from '@/lib/wrap';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Percent Slide Carousel
   --------------------------------------------------------------------------
   The boring, correct one. A flex track whose slides are each 100% of the
   track's width; the track translates by `-100% * index`. One CSS transition,
   no library, no measurement, no listeners, nothing to clean up.

   Percentage translation works here for a reason worth understanding: the
   track is `width: 100%` of the viewport box, each slide is `width: 100%` of
   the *track*, and `flex-shrink: 0` lets them overflow instead of compressing.
   So one track-width is exactly one slide-width, and `-100%` is exactly one
   slide. Change any one of those three and the arithmetic breaks silently.
   ========================================================================== */

export interface PercentSlideCarouselProps {
  /** One slide per child. */
  children: ReactNode;
  /** Slide transition duration in ms. */
  duration?: number;
  /** Controlled index. Omit for uncontrolled. */
  index?: number;
  defaultIndex?: number;
  onIndexChange?: (index: number) => void;
  /** Wrap from the last slide back to the first. Off by default — see notes. */
  loop?: boolean;
  className?: string;
  slideClassName?: string;
  'aria-label'?: string;
}

const EASE = 'cubic-bezier(0.22, 1, 0.36, 1)';

export function PercentSlideCarousel({
  children,
  duration = 600,
  index,
  defaultIndex = 0,
  onIndexChange,
  loop = false,
  className,
  slideClassName,
  'aria-label': ariaLabel = 'Carousel',
}: PercentSlideCarouselProps) {
  const items = Children.toArray(children);
  const count = items.length;
  const reduced = useReducedMotion();

  const [internal, setInternal] = useState(defaultIndex);
  const current = index ?? internal;

  const go = useCallback(
    (next: number) => {
      const resolved = loop
        ? wrapIndex(next, count)
        : clamp(next, 0, Math.max(0, count - 1));
      if (index === undefined) setInternal(resolved);
      onIndexChange?.(resolved);
    },
    [count, loop, index, onIndexChange],
  );

  const atStart = !loop && current <= 0;
  const atEnd = !loop && current >= count - 1;

  // #region critical
  const trackStyle = {
    // One slide is one track-width, so the step is exactly 100%. This is the
    // only carousel arithmetic that needs no numbers from layout at all.
    transform: `translateX(-${100 * current}%)`,
    // No transition under reduced motion: the slide still changes, it just
    // arrives instantly. Cutting the movement is the point; cutting the
    // navigation would be a bug.
    transition: reduced ? 'none' : `transform ${duration}ms ${EASE}`,
  };
  // #endregion critical

  return (
    <div
      className={cn('relative h-full w-full overflow-hidden', className)}
      role="group"
      aria-roledescription="carousel"
      aria-label={ariaLabel}
    >
      <div className="flex h-full w-full" style={trackStyle}>
        {items.map((child, i) => (
          <div
            key={isValidElement(child) && child.key !== null ? child.key : i}
            role="group"
            aria-roledescription="slide"
            aria-label={`${i + 1} of ${count}`}
            // `w-full shrink-0`: full width of the TRACK, and no shrinking, so
            // the slides overflow rather than being squeezed to fit. Drop
            // `shrink-0` and every slide compresses to 1/count of the track,
            // the translate still moves a full track-width, and the carousel
            // jumps `count` slides per click.
            className={cn('h-full w-full shrink-0', slideClassName)}
          >
            {child}
          </div>
        ))}
      </div>

      <button
        type="button"
        onClick={() => go(current - 1)}
        disabled={atStart}
        aria-label="Previous slide"
        className="absolute left-3 top-1/2 grid h-9 w-9 -translate-y-1/2 place-items-center rounded-full border border-line-strong bg-surface/70 text-fg backdrop-blur-sm transition-opacity hover:bg-surface disabled:pointer-events-none disabled:opacity-30"
      >
        <svg viewBox="0 0 24 24" aria-hidden className="h-4 w-4" fill="none">
          <path d="M14.5 5.5 8 12l6.5 6.5" stroke="currentColor" strokeWidth="1.25" strokeLinecap="square" />
        </svg>
      </button>
      <button
        type="button"
        onClick={() => go(current + 1)}
        disabled={atEnd}
        aria-label="Next slide"
        className="absolute right-3 top-1/2 grid h-9 w-9 -translate-y-1/2 place-items-center rounded-full border border-line-strong bg-surface/70 text-fg backdrop-blur-sm transition-opacity hover:bg-surface disabled:pointer-events-none disabled:opacity-30"
      >
        <svg viewBox="0 0 24 24" aria-hidden className="h-4 w-4" fill="none">
          <path d="M9.5 5.5 16 12l-6.5 6.5" stroke="currentColor" strokeWidth="1.25" strokeLinecap="square" />
        </svg>
      </button>
    </div>
  );
}

/* ==========================================================================
   Frame-rate-independent interpolation.
   --------------------------------------------------------------------------
   The everywhere-idiom `x += (target - x) * 0.1` is a bug: it converges twice
   as fast on a 120 Hz display as on a 60 Hz one, so the same code feels
   different on different hardware and visibly speeds up when the browser
   drops frames. `damp` fixes it by raising the retention factor to the power
   of elapsed time, which is the exact continuous form of the same curve.
   ========================================================================== */

/**
 * Fraction of the remaining distance to close this frame.
 *
 * @param smoothing Fraction of the gap that REMAINS after one second.
 *   Smaller is snappier. 0.001 ≈ very fast, 0.01 ≈ fast, 0.1 ≈ soft,
 *   0.5 ≈ slow drift.
 * @param dt Seconds elapsed since the previous frame.
 */
export function dampFactor(smoothing: number, dt: number): number {
  return 1 - Math.pow(smoothing, dt);
}

/** Move `current` toward `target` at a rate independent of frame rate. */
export function damp(
  current: number,
  target: number,
  smoothing: number,
  dt: number,
): number {
  return current + (target - current) * dampFactor(smoothing, dt);
}

/**
 * The per-frame lerp constant an author measured at 60fps, converted into the
 * `smoothing` argument `damp` wants. Lets a source that says "0.1 per frame"
 * be ported without re-tuning by eye:
 *
 *   damp(x, t, perFrameToSmoothing(0.1), dt)
 */
export function perFrameToSmoothing(alpha: number, baseFps = 60): number {
  return Math.pow(1 - alpha, baseFps);
}

export function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

export function clamp(v: number, min: number, max: number): number {
  return v < min ? min : v > max ? max : v;
}

export function inverseLerp(a: number, b: number, v: number): number {
  return a === b ? 0 : (v - a) / (b - a);
}

export function mapRange(
  v: number,
  inMin: number,
  inMax: number,
  outMin: number,
  outMax: number,
  doClamp = true,
): number {
  const t = inverseLerp(inMin, inMax, v);
  const r = lerp(outMin, outMax, doClamp ? clamp(t, 0, 1) : t);
  return r;
}

/** GLSL `smoothstep`, same semantics, for parity between JS and shader code. */
export function smoothstep(edge0: number, edge1: number, x: number): number {
  const t = clamp(inverseLerp(edge0, edge1, x), 0, 1);
  return t * t * (3 - 2 * t);
}

/**
 * Gaussian falloff, `exp(-d²)`. Yields 1.000 / 0.368 / 0.018 / 0.0001 at
 * distances 0 / 1 / 2 / 3 — a continuous focus scalar with no thresholds and
 * no branches, which is why carousels that use it feel analogue rather than
 * stepped.
 */
export function gaussian(distance: number, falloff = 1): number {
  const d = distance * falloff;
  return Math.exp(-(d * d));
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   prefers-reduced-motion, SSR-safe.
   --------------------------------------------------------------------------
   useSyncExternalStore rather than useState + useEffect: the server snapshot
   is an explicit `false`, so the markup React renders on the server and the
   markup it hydrates with agree, and the real value lands in the same commit
   as hydration instead of one frame later. A useEffect version flashes the
   animated variant before removing it — the exact thing the user asked not to
   see.

   Reduced motion is not "duration: 0". For most components here it means a
   different render: the final state, a static poster, or a paused frame.
   ========================================================================== */

const QUERY = '(prefers-reduced-motion: reduce)';

function subscribe(onChange: () => void) {
  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
  const mql = window.matchMedia(QUERY);
  mql.addEventListener('change', onChange);
  return () => mql.removeEventListener('change', onChange);
}

function getSnapshot() {
  if (typeof window === 'undefined' || !window.matchMedia) return false;
  return window.matchMedia(QUERY).matches;
}

function getServerSnapshot() {
  return false;
}

export function useReducedMotion(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

/** Generic media-query hook, same SSR guarantees. */
export function useMediaQuery(query: string): boolean {
  return useSyncExternalStore(
    (onChange) => {
      if (typeof window === 'undefined' || !window.matchMedia) return () => {};
      const mql = window.matchMedia(query);
      mql.addEventListener('change', onChange);
      return () => mql.removeEventListener('change', onChange);
    },
    () => {
      if (typeof window === 'undefined' || !window.matchMedia) return false;
      return window.matchMedia(query).matches;
    },
    () => false,
  );
}

/* ==========================================================================
   Ring index arithmetic.
   --------------------------------------------------------------------------
   Anything that loops — a drum carousel, an infinite marquee, a cylinder of
   image planes — needs to answer "how far is item i from position p" in a way
   that treats the sequence as a circle. A plain `i - p` says item 0 is 18 away
   from item 18 in a list of 19, when really it is 1 step back.
   ========================================================================== */

/** True modulo. Unlike `%`, the result is never negative. */
export function mod(n: number, m: number): number {
  return ((n % m) + m) % m;
}

/**
 * Shortest signed distance from `position` to index `i` around a ring of
 * `count` items. Result is in `(-count/2, count/2]`; negative means "behind".
 *
 * This one function is what makes a finite array behave like an infinite one.
 */
export function wrappedOffset(i: number, position: number, count: number): number {
  if (count <= 0) return 0;
  let offset = mod(i - position, count);
  if (offset > count / 2) offset -= count;
  return offset;
}

/** Wrap `value` into `[min, max)`, e.g. an angle into `[-PI, PI)`. */
export function wrapRange(value: number, min: number, max: number): number {
  const span = max - min;
  if (span <= 0) return min;
  return mod(value - min, span) + min;
}

/** Wrap an index into `[0, count)`. Accepts fractional and negative input. */
export function wrapIndex(i: number, count: number): number {
  return count <= 0 ? 0 : mod(i, count);
}

/**
 * Shortest signed angular distance from `a` to `b` in radians, in `(-PI, PI]`.
 * Prevents a rotation tween from taking the long way round.
 */
export function shortestAngle(a: number, b: number): number {
  return wrapRange(b - a, -Math.PI, Math.PI);
}