"use client"; /** * @author: @dorianbaffier * @description: Flick Card * @version: 2.0.0 * @date: 2026-10-14 * @license: MIT * @website: https://kokonutui.com * @github: https://github.com/kokonut-labs/kokonutui */ import { type KeyboardEvent, type PointerEvent, type ReactNode, type Ref, useCallback, useEffect, useId, useRef, useState, } from "react"; import { cn } from "@/lib/utils"; // Degrees of turn per px of drag. const DEG_PER_PX = 0.6; // Spring that lands the card on a face, in degrees and seconds. const STIFFNESS = 170; const DAMPING = 20; // How far ahead (in seconds of release velocity) the landing face is picked. const PROJECTION = 0.22; // A release faster than this (deg/s) always turns at least one face. const FLICK_SPEED = 450; // Never spin more than this many half turns from one flick. const MAX_HALF_TURNS = 6; // Movement below this (px) is a click, not a drag. const DRAG_SLOP = 4; // How far the card lifts toward the viewer at 90°, in px. const LIFT = 36; // Hover pre-tilt toward the pointer, in degrees. const TILT = 6; // Card thickness: stacked slices between the two faces. const THICKNESS = 6; const SLICES = 7; const SLICE_DEPTHS = Array.from( { length: SLICES }, (_, i) => -THICKNESS / 2 + (THICKNESS * (i + 0.5)) / SLICES ); const SUBSTEP = 1 / 240; // Release velocity is read from the last this-many ms of the drag. const VELOCITY_WINDOW = 80; const INTERACTIVE = "button, a, input, select, textarea, [data-no-flip]"; type Axis = "x" | "y"; export interface CardFlipProps { /** Front face. Defaults to an event ticket. */ front?: ReactNode; /** Back face. Defaults to the ticket's entry code and seat. */ back?: ReactNode; /** Controlled side: true shows the back. */ flipped?: boolean; /** Starting side when uncontrolled. */ defaultFlipped?: boolean; /** Called when a drag, click or key turns the card to the other side. */ onFlippedChange?: (flipped: boolean) => void; /** "y" spins left and right like a coin, "x" tumbles top over bottom. */ axis?: Axis; /** Accessible name of the card. */ label?: string; className?: string; /** Classes for both faces, such as background, border and radius. */ faceClassName?: string; } const mod2 = (n: number) => ((n % 2) + 2) % 2; const sideOf = (angle: number) => mod2(Math.round(angle / 180)) === 1; const nearestFace = (angle: number) => Math.round(angle / 180) * 180; interface Sim { angle: number; velocity: number; target: number; raf: number; last: number; reduceMotion: boolean; pointerId: number | null; startX: number; startY: number; startAngle: number; dragging: boolean; samples: { t: number; a: number }[]; } function cardTransform(axis: Axis, angle: number, lift: number) { const rotate = axis === "y" ? "rotateY" : "rotateX"; return `translateZ(${lift.toFixed(2)}px) ${rotate}(${angle.toFixed(2)}deg)`; } // A flat band of light sweeps across whichever face is showing, and the face // dims as it turns away from the light. function paintLight( axis: Axis, sin: number, bands: (HTMLDivElement | null)[], shades: (HTMLDivElement | null)[] ) { const turn = Math.abs(sin); const shift = `${(sin * 140).toFixed(1)}%`; const transform = axis === "y" ? `translateX(${shift}) rotate(18deg)` : `translateY(${shift}) rotate(72deg)`; for (const band of bands) { if (band) { band.style.opacity = (turn * 0.12).toFixed(3); band.style.transform = transform; } } for (const shade of shades) { if (shade) { shade.style.opacity = (turn * 0.14).toFixed(3); } } } function releaseVelocity(samples: Sim["samples"], now: number) { const last = samples.at(-1); if (!last || now - last.t > VELOCITY_WINDOW) { return 0; } const first = samples.find((p) => last.t - p.t <= VELOCITY_WINDOW); if (!first || last.t <= first.t) { return 0; } return ((last.a - first.a) / (last.t - first.t)) * 1000; } export default function CardFlip({ front, back, flipped, defaultFlipped = false, onFlippedChange, axis = "y", label = "Event ticket", className, faceClassName, }: CardFlipProps) { const isControlled = flipped !== undefined; const [internalFlipped, setInternalFlipped] = useState(defaultFlipped); const isFlipped = isControlled ? flipped : internalFlipped; // Which face is turned toward the viewer right now (changes at 90°). const [backVisible, setBackVisible] = useState(isFlipped); // Bumped when a controlled card asks to turn; see the effect below. const [request, setRequest] = useState(0); const hintId = useId(); const rootRef = useRef(null); const tiltRef = useRef(null); const cardRef = useRef(null); const shadowRef = useRef(null); const frontBandRef = useRef(null); const backBandRef = useRef(null); const frontShadeRef = useRef(null); const backShadeRef = useRef(null); // Styles React writes once; the spring owns them after that. const [initial] = useState(() => { const angle = isFlipped ? 180 : 0; return { angle, card: { transform: cardTransform(axis, angle, 0) }, front: { transform: `translateZ(${THICKNESS / 2}px)` }, }; }); const sim = useRef({ angle: initial.angle, velocity: 0, target: initial.angle, raf: 0, last: 0, reduceMotion: false, pointerId: null, startX: 0, startY: 0, startAngle: 0, dragging: false, samples: [], }); // Latest props for the imperative handlers. const latest = useRef({ axis, isFlipped, isControlled, onFlippedChange }); latest.current = { axis, isFlipped, isControlled, onFlippedChange }; const backVisibleRef = useRef(backVisible); const render = useCallback(() => { const s = sim.current; const ax = latest.current.axis; const rad = (s.angle * Math.PI) / 180; const sin = Math.sin(rad); const turn = Math.abs(sin); const facing = Math.abs(Math.cos(rad)); if (cardRef.current) { cardRef.current.style.transform = cardTransform(ax, s.angle, turn * LIFT); } if (shadowRef.current) { const narrow = (0.16 + 0.84 * facing).toFixed(3); const soft = (1 - turn * 0.12).toFixed(3); shadowRef.current.style.transform = ax === "y" ? `scale(${narrow}, ${soft})` : `scale(${soft}, ${narrow})`; shadowRef.current.style.opacity = (1 - turn * 0.45).toFixed(3); } paintLight( ax, sin, [frontBandRef.current, backBandRef.current], [frontShadeRef.current, backShadeRef.current] ); const showsBack = sideOf(s.angle); if (showsBack !== backVisibleRef.current) { backVisibleRef.current = showsBack; setBackVisible(showsBack); } }, []); const step = useCallback( (now: number) => { const s = sim.current; const dt = Math.min(0.05, (now - s.last) / 1000); s.last = now; const n = Math.max(1, Math.ceil(dt / SUBSTEP)); const h = dt / n; for (let i = 0; i < n; i++) { const force = -STIFFNESS * (s.angle - s.target) - DAMPING * s.velocity; s.velocity += force * h; s.angle += s.velocity * h; } if (Math.abs(s.angle - s.target) < 0.05 && Math.abs(s.velocity) < 0.5) { // Settled: park on 0 or 180 so the numbers never grow, then sleep. s.target = sideOf(s.target) ? 180 : 0; s.angle = s.target; s.velocity = 0; s.raf = 0; render(); return; } render(); s.raf = requestAnimationFrame(step); }, [render] ); const settle = useCallback(() => { const s = sim.current; if (s.reduceMotion) { // Reduced motion: no spin, land on the face at once. cancelAnimationFrame(s.raf); s.raf = 0; s.target = sideOf(s.target) ? 180 : 0; s.angle = s.target; s.velocity = 0; render(); return; } if (!s.raf) { s.last = performance.now(); s.raf = requestAnimationFrame(step); } }, [render, step]); // Point the spring at a face and report a side change. const aim = useCallback( (target: number) => { sim.current.target = target; const next = sideOf(target); const p = latest.current; if (next !== p.isFlipped) { if (p.isControlled) { setRequest((n) => n + 1); } else { setInternalFlipped(next); } p.onFlippedChange?.(next); } settle(); }, [settle] ); const flipBy = useCallback( (direction: number) => { aim(nearestFace(sim.current.target) + 180 * direction); }, [aim] ); useEffect(() => { const s = sim.current; const query = window.matchMedia("(prefers-reduced-motion: reduce)"); s.reduceMotion = query.matches; const onChange = () => { s.reduceMotion = query.matches; }; query.addEventListener("change", onChange); return () => { query.removeEventListener("change", onChange); cancelAnimationFrame(s.raf); s.raf = 0; }; }, []); // Controlled: follow the prop when it disagrees with where the card lands. // `request` re-runs this after every turn the card asks for, so a parent // that ignores onFlippedChange sends the card back to its side. useEffect(() => { if (flipped === undefined || request < 0) { return; } const s = sim.current; if (s.dragging || sideOf(s.target) === flipped) { return; } // The nearest face on the asked-for side, so a refused turn swings back // the way it came. const face = nearestFace(s.angle); if (sideOf(face) === flipped) { s.target = face; } else { s.target = face + (s.angle < face ? -180 : 180); } settle(); }, [flipped, request, settle]); // A new axis redraws the spring-owned transforms in place. useEffect(() => { latest.current.axis = axis; render(); }, [axis, render]); const setTilt = (x: number, y: number) => { if (tiltRef.current) { tiltRef.current.style.transform = `rotateX(${(-y * TILT).toFixed(2)}deg) rotateY(${(x * TILT).toFixed(2)}deg)`; } }; const onPointerDown = (e: PointerEvent) => { const s = sim.current; // One pointer at a time: a second finger does not steal the drag. if ( s.pointerId !== null || e.button !== 0 || (e.target as Element).closest(INTERACTIVE) ) { return; } s.pointerId = e.pointerId; s.startX = e.clientX; s.startY = e.clientY; s.startAngle = s.angle; s.dragging = false; s.samples = [{ t: e.timeStamp, a: s.angle }]; e.currentTarget.setPointerCapture(e.pointerId); }; const hoverTilt = (e: PointerEvent) => { // The tilt follows the cursor: it's movement, so reduced motion skips it. if ( e.pointerType !== "mouse" || sim.current.reduceMotion || !rootRef.current ) { return; } const r = rootRef.current.getBoundingClientRect(); setTilt( ((e.clientX - r.left) / r.width) * 2 - 1, ((e.clientY - r.top) / r.height) * 2 - 1 ); }; const onPointerMove = (e: PointerEvent) => { const s = sim.current; if (s.pointerId !== e.pointerId) { hoverTilt(e); return; } const dx = e.clientX - s.startX; const dy = e.clientY - s.startY; if (!s.dragging) { if (Math.hypot(dx, dy) < DRAG_SLOP) { return; } s.dragging = true; cancelAnimationFrame(s.raf); s.raf = 0; s.velocity = 0; setTilt(0, 0); } // One to one: the card stays under the finger. s.angle = s.startAngle + (axis === "y" ? dx : -dy) * DEG_PER_PX; s.samples.push({ t: e.timeStamp, a: s.angle }); if (s.samples.length > 8) { s.samples.shift(); } render(); }; const release = (e: PointerEvent, cancelled: boolean) => { const s = sim.current; if (s.pointerId !== e.pointerId) { return; } s.pointerId = null; if (!s.dragging) { if (!cancelled) { // A click pushes the half you pressed away from you. const r = e.currentTarget.getBoundingClientRect(); const pushed = axis === "y" ? e.clientX > r.left + r.width / 2 : e.clientY < r.top + r.height / 2; flipBy(pushed ? 1 : -1); } return; } s.dragging = false; const velocity = cancelled ? 0 : releaseVelocity(s.samples, e.timeStamp); const from = nearestFace(s.startAngle); let target = nearestFace(s.angle + velocity * PROJECTION); if (Math.abs(velocity) > FLICK_SPEED && target === from) { target = from + 180 * Math.sign(velocity); } const limit = MAX_HALF_TURNS * 180; target = Math.max(from - limit, Math.min(from + limit, target)); s.velocity = velocity; aim(target); }; const onKeyDown = (e: KeyboardEvent) => { if (e.target !== e.currentTarget) { return; } if (e.key === "Enter" || e.key === " ") { e.preventDefault(); flipBy(1); } }; const face = cn( "absolute inset-0 overflow-hidden rounded-2xl [backface-visibility:hidden]", "border border-zinc-200 bg-white text-zinc-900", "dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-50", faceClassName ); return ( // biome-ignore lint/a11y/useSemanticElements: a labelled card whose faces hold their own content, not a plain button // biome-ignore lint/a11y/noNoninteractiveElementInteractions: drag, click and Enter or Space all turn the card

release(e, true)} onPointerCancel={(e) => release(e, true)} onPointerDown={onPointerDown} onPointerLeave={() => { if (sim.current.pointerId === null) { setTilt(0, 0); } }} onPointerMove={onPointerMove} onPointerUp={(e) => release(e, false)} ref={rootRef} role="group" // biome-ignore lint/a11y/noNoninteractiveTabindex: Enter and Space flip the card while it has focus tabIndex={0} > {/* Floor shadow: narrows and fades as the card turns edge-on. */}

{/* The edge: thin slices stacked between the two faces. */} {SLICE_DEPTHS.map((z) => (

Showing the {isFlipped ? "back" : "front"}. Press Enter or Space, or drag, to turn it over.

); } function LightBand({ bandRef, shadeRef, }: { bandRef: Ref; shadeRef: Ref; }) { return (

); } /* Demo faces: an event ticket. Pass your own front and back to replace them. */ const TICKET = { event: "Fieldwork Sessions", edition: "Vol. 04", date: "Sat 21 Nov", time: "19:30", venue: "Hall B, Pier 7", holder: "Jordan Vale", number: "004182", gate: "C", section: "Floor", row: "F", seat: "14", }; function TicketFront() { return (

Admit one GA

{TICKET.edition}

{TICKET.event}

Holder

{TICKET.holder}

No. {TICKET.number}

); } function TicketBack() { return (

Scan at entry #{TICKET.number}

Valid for one entry. Re-entry with wristband only.

); } function TicketField({ label, value, wide, }: { label: string; value: string; wide?: boolean; }) { return (

{label}

{value}

); } // A deterministic, QR-like code: three finder squares and seeded modules. const QR_SIZE = 21; const QR_PATH = buildQrPath(QR_SIZE, 4182); function buildQrPath(size: number, seed: number) { let state = seed; const random = () => { state = (state * 16_807) % 2_147_483_647; return state / 2_147_483_647; }; const far = size - 7; const inFinder = (x: number, y: number) => (x < 8 && y < 8) || (x >= far - 1 && y < 8) || (x < 8 && y >= far - 1); const finderCell = (x: number, y: number) => { const fx = x >= far ? x - far : x; const fy = y >= far ? y - far : y; if (fx > 6 || fy > 6 || fx < 0 || fy < 0) { return false; } return Math.max(Math.abs(fx - 3), Math.abs(fy - 3)) !== 2; }; let d = ""; for (let y = 0; y < size; y++) { for (let x = 0; x < size; x++) { const on = inFinder(x, y) ? finderCell(x, y) : random() > 0.52; if (on) { d += `M${x} ${y}h1v1h-1z`; } } } return d; }

Flick Card

Fieldwork Sessions

On this page

Fieldwork Sessions