react-raffle-picker 0.3.1 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 
   <h1>react-raffle-picker</h1>
 
-  <p><strong>React like you just won. The raffle picker your UI deserves.</strong></p>
+  <p><strong>Random winner picker for React.</strong><br/>Giveaways, raffles, prize draws and slot-machine UIs — headless, typed, zero dependencies.</p>
 
   <p>
     <a href="https://react-raffle-one.vercel.app/">Live demo</a>
@@ -27,7 +27,16 @@
   </p>
 </div>
 
-A headless, composable React component for giveaways, raffles, and slot-machine UIs. Cycles numbers or names with smooth animations and freezes on a winner. Performant on slow devices — high-frequency tick updates bypass React.
+Pick a random winner in React. `react-raffle-picker` cycles a list of names or a number range,
+freezes on a winner, and never draws the same one twice — with slot-machine reels, four CSS
+animations and countdown auto-freeze.
+
+It ships as a **headless compound component**: no layout opinions, no style props soup, you
+bring your own CSS. Performant on slow devices — high-frequency tick updates bypass React and
+write to the DOM via refs.
+
+**Use it for:** giveaway winners on stream · prize draws · random name picker · standup speaking
+order · random number roller · slot-machine and lottery UIs.
 
 ```bash
 npm install react-raffle-picker
@@ -71,7 +80,6 @@ This means:
 
 ```tsx
 import { RafflePick } from 'react-raffle-picker'
-
 ;<RafflePick min={1} max={100} interval={100} inertia onSelect={(v) => console.log(v)}>
   <RafflePick.Value animation="roll" className="my-value" />
   <RafflePick.Button startLabel="Pick" stopLabel="Stop" />
@@ -107,11 +115,11 @@ Provides context. Renders an optional wrapper element (`as` prop, default `'div'
 | `random`       | `boolean`                   | `true`     | Random pick vs sequential.                                                                                                                                               |
 | `inertia`      | `boolean`                   | `false`    | Soft start / soft stop ramp.                                                                                                                                             |
 | `autoStart`    | `boolean`                   | `true`     | Begin cycling on mount.                                                                                                                                                  |
-| `noRepeat`     | `boolean`                   | `true`     | Exclude previously frozen values from later rounds — no duplicate winners across sequential draws in the same mounted instance. Set `false` to allow repeats.           |
+| `noRepeat`     | `boolean`                   | `true`     | Exclude previously frozen values from later rounds — no duplicate winners across sequential draws in the same mounted instance. Set `false` to allow repeats.            |
 | `initialValue` | `number \| string`          | —          | Starting display before first run. Number for `min`/`max` mode, string for `items` mode. For `<Slots>`, each character seeds the corresponding reel.                     |
 | `finalValue`   | `number \| string`          | —          | Forces settle to land on this value. Cycle still appears random; only final freeze is rigged. For `<Slots>`, each character is the final char of the corresponding reel. |
 | `onSelect`     | `(value) => void`           | —          | Fires once per round on freeze.                                                                                                                                          |
-| `onExhausted`  | `() => void`                | —          | Fires when `start()` is called but `noRepeat` has already drawn every candidate.                                                                                        |
+| `onExhausted`  | `() => void`                | —          | Fires when `start()` is called but `noRepeat` has already drawn every candidate.                                                                                         |
 | `as`           | `ElementType`               | `'div'`    | Wrapper tag.                                                                                                                                                             |
 | `className`    | `string`                    | —          | Wrapper class.                                                                                                                                                           |
 | `style`        | `CSSProperties`             | —          | Wrapper style.                                                                                                                                                           |
@@ -136,15 +144,15 @@ Multiple `Value` instances inside one root are supported — all subscribe to th
 
 Toggles start / freeze based on phase. Disabled during settling.
 
-| Prop         | Type            | Notes                                            |
-| ------------ | --------------- | ------------------------------------------------ |
-| `startLabel` | `ReactNode`     | Shown in `idle` / `frozen` (click starts).       |
-| `stopLabel`  | `ReactNode`     | Shown in `running` / `starting` (click stops).   |
-| `waitLabel`  | `ReactNode`     | Shown in `settling` (button disabled).           |
-| `children`   | `ReactNode`     | Fallback label when state-specific label absent. |
+| Prop         | Type            | Notes                                                           |
+| ------------ | --------------- | --------------------------------------------------------------- |
+| `startLabel` | `ReactNode`     | Shown in `idle` / `frozen` (click starts).                      |
+| `stopLabel`  | `ReactNode`     | Shown in `running` / `starting` (click stops).                  |
+| `waitLabel`  | `ReactNode`     | Shown in `settling` (button disabled).                          |
+| `children`   | `ReactNode`     | Fallback label when state-specific label absent.                |
 | `disabled`   | `boolean`       | External disable, on top of the auto-disable during `settling`. |
-| `className`  | `string`        | —                                                |
-| `style`      | `CSSProperties` | —                                                |
+| `className`  | `string`        | —                                                               |
+| `style`      | `CSSProperties` | —                                                               |
 
 ### `<RafflePick.Countdown>`
 
@@ -172,6 +180,36 @@ Independent multi-reel slot machine. Each reel ticks on its own and stops with a
 | `onResult`                                         | `(joined: string) => void` | —              | Fires when the last reel lands.              |
 | `className`, `slotClassName`, `style`, `slotStyle` | various                    | —              | Style hooks.                                 |
 
+### `<RafflePick.Wheel>`
+
+Spinning wheel that lands on the value the root picks. Segments come from `items`, or from the `min`/`max` range in numeric mode.
+
+Needs no stylesheet — the geometry is inline SVG, rotation runs on `requestAnimationFrame`, and the landing is a single CSS transition, so nothing re-renders mid-spin. Respects `prefers-reduced-motion` by jumping straight to the result.
+
+> **Reveal on `onResult`, not `onSelect`.** The root commits the winner the instant it freezes, which is when the wheel *starts* its landing. Firing confetti or a result banner from the root's `onSelect` shows the answer `spinDuration` ms before the wheel gets there.
+
+| Prop            | Type                       | Default          | Notes                                                                                        |
+| --------------- | -------------------------- | ---------------- | -------------------------------------------------------------------------------------------- |
+| `segments`      | `string[]`                 | root pool        | Relabel segments. The winner is still chosen by the root; label `i` maps to pool position `i`. |
+| `size`          | `number`                   | `320`            | Outer diameter, px.                                                                          |
+| `colors`        | `string[]`                 | 6-color palette  | Segment fills, cycled.                                                                       |
+| `labelColor`    | `string`                   | `'#fff'`         | Label text color.                                                                            |
+| `maxLabels`     | `number`                   | `40`             | Past this many segments labels are hidden — they overlap into noise. Segments still work.     |
+| `spinDuration`  | `number` (ms)              | `4200`           | Landing animation length, from freeze to rest.                                                |
+| `turns`         | `number`                   | `4`              | Extra full revolutions before the landing angle.                                              |
+| `spinInterval`  | `number` (ms per turn)     | `1800`           | Free-spin speed while running.                                                                |
+| `pointer`       | `'top' \| 'right'`         | `'top'`          | Where the pointer sits on the rim.                                                            |
+| `hidePointer`   | `boolean`                  | `false`          | Drop the built-in triangle to render your own.                                                |
+| `onResult`      | `(value) => void`          | —                | Fires when the wheel comes to rest.                                                           |
+| `className`, `style` | various               | —                | Style hooks.                                                                                  |
+
+```tsx
+<RafflePick items={['Alice', 'Bob', 'Carol']} autoStart={false}>
+  <RafflePick.Wheel size={340} onResult={(winner) => celebrate(winner)} />
+  <RafflePick.Button startLabel="Spin" stopLabel="Stop" />
+</RafflePick>
+```
+
 ## Recipes
 
 ### Inline chip in a sentence
@@ -260,7 +298,7 @@ function Giveaway() {
 ## Accessibility
 
 - `<RafflePick.Value>` cycles are visual-only (`aria-hidden`) — high-frequency tick
-  updates are not announced. The frozen result *is* announced once per round via a
+  updates are not announced. The frozen result _is_ announced once per round via a
   hidden `aria-live="polite"` region.
 - `<RafflePick.Countdown>`'s ring/label are `aria-hidden`; a one-time sr-only
   announcement fires when the countdown starts. The result itself is still

package/dist/index.cjs

@@ -205,6 +205,11 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		const its = itemsRef.current;
 		return its && its.length > 0 ? its[index] : index;
 	}, []);
+	const valueAt = (0, react.useCallback)((position) => {
+		const its = itemsRef.current;
+		if (its && its.length > 0) return its[position];
+		return cycleMin + position;
+	}, [cycleMin]);
 	const valueToIndex = (0, react.useCallback)((value) => {
 		if (value === void 0) return void 0;
 		const its = itemsRef.current;
@@ -320,8 +325,10 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		noRepeat,
 		exhausted,
 		remaining,
+		total: totalCandidates,
 		valueRef,
 		displayValue,
+		valueAt,
 		subscribe,
 		start: guardedStart,
 		freeze,
@@ -340,7 +347,9 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		noRepeat,
 		exhausted,
 		remaining,
+		totalCandidates,
 		displayValue,
+		valueAt,
 		subscribe,
 		guardedStart,
 		freeze,
@@ -718,12 +727,293 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 	});
 }
 //#endregion
+//#region src/components/RafflePick/RafflePickWheel.tsx
+const DEFAULT_COLORS = [
+	"#7c1d29",
+	"#d4a04a",
+	"#2f4858",
+	"#a83b2c",
+	"#ecc878",
+	"#4a0f18"
+];
+const VIEWBOX = 100;
+const CENTER = VIEWBOX / 2;
+const RADIUS = 48;
+const LABEL_RADIUS = RADIUS * .66;
+const prefersReducedMotion = () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+/** Point on the wheel rim at `deg`, measured clockwise from 12 o'clock. */
+const rimPoint = (deg, radius) => {
+	const rad = (deg - 90) * Math.PI / 180;
+	return {
+		x: CENTER + radius * Math.cos(rad),
+		y: CENTER + radius * Math.sin(rad)
+	};
+};
+const segmentPath = (index, total) => {
+	const sweep = 360 / total;
+	const a0 = index * sweep;
+	const a1 = a0 + sweep;
+	const p0 = rimPoint(a0, RADIUS);
+	const p1 = rimPoint(a1, RADIUS);
+	const largeArc = sweep > 180 ? 1 : 0;
+	return `M ${CENTER} ${CENTER} L ${p0.x} ${p0.y} A ${RADIUS} ${RADIUS} 0 ${largeArc} 1 ${p1.x} ${p1.y} Z`;
+};
+/**
+* Rotation, in degrees, that parks the centre of segment `position` under a
+* pointer sitting at `pointerDeg` clockwise from 12 o'clock.
+*/
+const restAngleFor = (position, total, pointerDeg) => pointerDeg - (position + .5) * (360 / total);
+/**
+* Next rotation past `from` that lands on `position`, after at least `turns`
+* more full revolutions. Always forward, so the wheel never visibly rewinds.
+*/
+const landingAngle = (from, position, total, turns, pointerDeg) => {
+	const base = from + turns * 360;
+	return base + ((restAngleFor(position, total, pointerDeg) - base) % 360 + 360) % 360;
+};
+function RafflePickWheel({ segments, size = 320, colors = DEFAULT_COLORS, labelColor = "#fff", maxLabels = 40, spinDuration = 4200, turns = 4, spinInterval = 1800, pointer = "top", hidePointer = false, className, style, onResult }) {
+	const { phase, total, valueAt, valueRef, hasItems, displayed } = useRaffleContext("RafflePick.Wheel");
+	const count = segments?.length ?? total;
+	const safeCount = Math.max(1, count);
+	const labels = (0, react.useMemo)(() => {
+		if (segments) return segments;
+		return Array.from({ length: safeCount }, (_, i) => String(valueAt(i)));
+	}, [
+		segments,
+		safeCount,
+		valueAt
+	]);
+	const indexOffset = (0, react.useMemo)(() => {
+		if (hasItems || segments) return 0;
+		const first = valueAt(0);
+		return typeof first === "number" ? first : 0;
+	}, [
+		hasItems,
+		segments,
+		valueAt
+	]);
+	const pointerDeg = pointer === "right" ? 90 : 0;
+	const wheelRef = (0, react.useRef)(null);
+	const rootRef = (0, react.useRef)(null);
+	const liveRef = (0, react.useRef)(null);
+	const rotationRef = (0, react.useRef)(0);
+	const rafRef = (0, react.useRef)(null);
+	const lastFrameRef = (0, react.useRef)(0);
+	const setResting = (0, react.useCallback)((rest, announce) => {
+		const root = rootRef.current;
+		if (root) if (rest) root.setAttribute("data-resting", "");
+		else root.removeAttribute("data-resting");
+		const live = liveRef.current;
+		if (live) live.textContent = rest && announce !== void 0 ? announce : "";
+	}, []);
+	const onResultRef = (0, react.useRef)(onResult);
+	(0, react.useEffect)(() => {
+		onResultRef.current = onResult;
+	});
+	const write = (0, react.useCallback)((deg) => {
+		const node = wheelRef.current;
+		if (node) node.style.transform = `rotate(${deg}deg)`;
+	}, []);
+	const spinning = phase === "starting" || phase === "running" || phase === "settling";
+	(0, react.useEffect)(() => {
+		if (!spinning) return;
+		setResting(false);
+		if (prefersReducedMotion()) return;
+		const node = wheelRef.current;
+		if (node) node.style.transition = "none";
+		lastFrameRef.current = 0;
+		const frame = (now) => {
+			const last = lastFrameRef.current || now;
+			lastFrameRef.current = now;
+			rotationRef.current += (now - last) / Math.max(200, spinInterval) * 360;
+			write(rotationRef.current);
+			rafRef.current = requestAnimationFrame(frame);
+		};
+		rafRef.current = requestAnimationFrame(frame);
+		return () => {
+			if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+			rafRef.current = null;
+		};
+	}, [
+		spinning,
+		spinInterval,
+		write,
+		setResting
+	]);
+	(0, react.useEffect)(() => {
+		if (phase !== "frozen") return;
+		const position = Math.min(safeCount - 1, Math.max(0, valueRef.current - indexOffset));
+		const node = wheelRef.current;
+		if (prefersReducedMotion() || !node) {
+			rotationRef.current = restAngleFor(position, safeCount, pointerDeg);
+			write(rotationRef.current);
+			setResting(true, String(displayed));
+			onResultRef.current?.(displayed);
+			return;
+		}
+		const target = landingAngle(rotationRef.current, position, safeCount, Math.max(0, turns), pointerDeg);
+		rotationRef.current = target;
+		node.style.transition = `transform ${spinDuration}ms cubic-bezier(0.16, 1, 0.3, 1)`;
+		node.getBoundingClientRect();
+		write(target);
+		let done = false;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			setResting(true, String(displayed));
+			onResultRef.current?.(displayed);
+		};
+		node.addEventListener("transitionend", finish, { once: true });
+		const fallback = setTimeout(finish, spinDuration + 120);
+		return () => {
+			node.removeEventListener("transitionend", finish);
+			clearTimeout(fallback);
+		};
+	}, [
+		phase,
+		safeCount,
+		indexOffset,
+		turns,
+		spinDuration,
+		write,
+		valueRef,
+		displayed,
+		pointerDeg,
+		setResting
+	]);
+	(0, react.useEffect)(() => {
+		if (phase !== "idle") return;
+		const position = Math.min(safeCount - 1, Math.max(0, valueRef.current - indexOffset));
+		const node = wheelRef.current;
+		if (node) node.style.transition = "none";
+		rotationRef.current = restAngleFor(position, safeCount, pointerDeg);
+		write(rotationRef.current);
+		setResting(true);
+	}, [
+		phase,
+		safeCount,
+		indexOffset,
+		write,
+		valueRef,
+		pointerDeg,
+		setResting
+	]);
+	const showLabels = safeCount <= maxLabels;
+	const fontSize = Math.max(2.2, Math.min(5, 42 / safeCount + 1.6));
+	const paths = (0, react.useMemo)(() => Array.from({ length: safeCount }, (_, i) => ({
+		d: safeCount === 1 ? "" : segmentPath(i, safeCount),
+		fill: colors[i % colors.length],
+		mid: (i + .5) * (360 / safeCount)
+	})), [safeCount, colors]);
+	const cls = joinClassNames("rrp-wheel", className);
+	const pointerStyle = pointer === "right" ? {
+		position: "absolute",
+		top: "50%",
+		right: -2,
+		width: 0,
+		height: 0,
+		transform: "translateY(-50%)",
+		borderTop: `${size * .045}px solid transparent`,
+		borderBottom: `${size * .045}px solid transparent`,
+		borderRight: `${size * .09}px solid currentColor`
+	} : {
+		position: "absolute",
+		left: "50%",
+		top: -2,
+		width: 0,
+		height: 0,
+		transform: "translateX(-50%)",
+		borderLeft: `${size * .045}px solid transparent`,
+		borderRight: `${size * .045}px solid transparent`,
+		borderTop: `${size * .09}px solid currentColor`
+	};
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		ref: rootRef,
+		className: cls,
+		style: {
+			position: "relative",
+			display: "inline-block",
+			lineHeight: 0,
+			...style,
+			width: size,
+			height: size
+		},
+		"data-phase": phase,
+		"data-pointer": pointer,
+		"data-resting": "",
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+				ref: wheelRef,
+				className: "rrp-wheel__disc",
+				style: {
+					display: "block",
+					transformOrigin: "50% 50%",
+					willChange: "transform"
+				},
+				viewBox: `0 0 ${VIEWBOX} ${VIEWBOX}`,
+				width: size,
+				height: size,
+				role: "img",
+				"aria-label": `Wheel with ${safeCount} segments`,
+				children: [safeCount === 1 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("circle", {
+					cx: CENTER,
+					cy: CENTER,
+					r: RADIUS,
+					fill: paths[0].fill
+				}) : paths.map((p, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
+					d: p.d,
+					fill: p.fill,
+					stroke: "rgba(0,0,0,0.14)",
+					strokeWidth: .3
+				}, i)), showLabels && paths.map((p, i) => {
+					const pt = rimPoint(p.mid, LABEL_RADIUS);
+					const rotate = p.mid > 180 ? p.mid + 90 : p.mid - 90;
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("text", {
+						x: pt.x,
+						y: pt.y,
+						fill: labelColor,
+						fontSize,
+						fontWeight: 600,
+						textAnchor: "middle",
+						dominantBaseline: "middle",
+						transform: `rotate(${rotate} ${pt.x} ${pt.y})`,
+						style: {
+							pointerEvents: "none",
+							userSelect: "none"
+						},
+						children: labels[i]
+					}, i);
+				})]
+			}),
+			!hidePointer && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "rrp-wheel__pointer",
+				style: pointerStyle,
+				"aria-hidden": "true"
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				ref: liveRef,
+				role: "status",
+				"aria-live": "polite",
+				style: {
+					position: "absolute",
+					width: 1,
+					height: 1,
+					overflow: "hidden",
+					clip: "rect(0, 0, 0, 0)",
+					whiteSpace: "nowrap"
+				}
+			})
+		]
+	});
+}
+//#endregion
 //#region src/components/RafflePick/index.ts
 const RafflePick = RafflePickRoot;
 RafflePick.Value = RafflePickValue;
 RafflePick.Button = RafflePickButton;
 RafflePick.Countdown = RafflePickCountdown;
 RafflePick.Slots = RafflePickSlots;
+RafflePick.Wheel = RafflePickWheel;
 //#endregion
 exports.RaffleContext = RaffleContext;
 exports.RafflePick = RafflePick;
@@ -731,4 +1021,5 @@ exports.RafflePickButton = RafflePickButton;
 exports.RafflePickCountdown = RafflePickCountdown;
 exports.RafflePickSlots = RafflePickSlots;
 exports.RafflePickValue = RafflePickValue;
+exports.RafflePickWheel = RafflePickWheel;
 exports.useRaffleContext = useRaffleContext;

package/dist/index.d.cts

@@ -94,6 +94,51 @@ interface RafflePickCountdownProps {
   /** Render-prop for fully custom output. Receives remaining seconds. */
   children?: (remaining: number) => ReactNode;
 }
+interface RafflePickWheelProps {
+  /**
+   * Segment labels. Defaults to the root's pool — `items`, or the `min`/`max`
+   * range. Pass this only to relabel segments; the winner is still chosen by
+   * the root, and label `i` maps to pool position `i`.
+   */
+  segments?: string[];
+  /** Outer diameter in px. Default `320`. */
+  size?: number;
+  /**
+   * Segment fill colors, cycled across segments. Defaults to a built-in
+   * 6-color palette. Adjacent segments never share a color as long as the
+   * palette length and segment count are not both even multiples.
+   */
+  colors?: string[];
+  /** Label text color. Default `'#fff'`. */
+  labelColor?: string;
+  /**
+   * Hide labels above this segment count — past it they overlap into noise.
+   * Colors and the landing still work. Default `40`. Set `Infinity` to force.
+   */
+  maxLabels?: number;
+  /** Landing animation duration in ms, from freeze to rest. Default `4200`. */
+  spinDuration?: number;
+  /** Full turns added before the landing angle, for a longer spin. Default `4`. */
+  turns?: number;
+  /** Idle/running rotation speed in ms per full turn. Default `1800`. */
+  spinInterval?: number;
+  /** Pointer position on the rim. Default `'top'`. */
+  pointer?: 'top' | 'right';
+  /** Hide the built-in pointer triangle to render your own. */
+  hidePointer?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Fires when the wheel physically comes to rest, with the winning value.
+   *
+   * Prefer this over the root's `onSelect` for anything the audience sees —
+   * a result banner, confetti, a sound. `onSelect` fires when the value is
+   * *committed*, which is the moment the landing animation **starts**, so
+   * reacting to it reveals the winner `spinDuration` ms before the wheel gets
+   * there.
+   */
+  onResult?: (value: RafflePickValue$1) => void;
+}
 //#endregion
 //#region src/components/RafflePick/RafflePick.d.ts
 declare function RafflePickRoot({
@@ -155,6 +200,23 @@ declare function RafflePickSlots({
   onResult
 }: RafflePickSlotsProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
+//#region src/components/RafflePick/RafflePickWheel.d.ts
+declare function RafflePickWheel({
+  segments,
+  size,
+  colors,
+  labelColor,
+  maxLabels,
+  spinDuration,
+  turns,
+  spinInterval,
+  pointer,
+  hidePointer,
+  className,
+  style,
+  onResult
+}: RafflePickWheelProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
 //#region src/utils/inertia.d.ts
 type RafflePickPhase = 'idle' | 'starting' | 'running' | 'settling' | 'frozen';
 //#endregion
@@ -175,8 +237,16 @@ interface RaffleContextValue {
   exhausted: boolean;
   /** Candidates left to draw. Equals the full pool size when `noRepeat` is off. */
   remaining: number;
+  /** Size of the draw pool: item count in items mode, `max - min + 1` in numeric mode. */
+  total: number;
   valueRef: RefObject<number>;
   displayValue: (index: number) => RafflePickValue$1;
+  /**
+   * Pool entry at a 0-based position, regardless of mode. `valueAt(0)` is the
+   * first item / `min`. Lets custom UIs enumerate the pool without knowing
+   * whether the root runs in items or numeric mode.
+   */
+  valueAt: (position: number) => RafflePickValue$1;
   subscribe: (fn: (value: number) => void) => () => void;
   start: () => void;
   freeze: () => void;
@@ -193,7 +263,8 @@ type RafflePickCompound = typeof RafflePickRoot & {
   Button: typeof RafflePickButton;
   Countdown: typeof RafflePickCountdown;
   Slots: typeof RafflePickSlots;
+  Wheel: typeof RafflePickWheel;
 };
 declare const RafflePick: RafflePickCompound;
 //#endregion
-export { type AnimationType, RaffleContext, type RaffleContextValue, RafflePick, RafflePickButton, type RafflePickButtonProps, RafflePickCountdown, type RafflePickCountdownProps, type RafflePickPhase, type RafflePickRootProps, RafflePickSlots, type RafflePickSlotsProps, RafflePickValue, type RafflePickValueProps, type RafflePickValue$1 as RafflePickValueType, useRaffleContext };
+export { type AnimationType, RaffleContext, type RaffleContextValue, RafflePick, RafflePickButton, type RafflePickButtonProps, RafflePickCountdown, type RafflePickCountdownProps, type RafflePickPhase, type RafflePickRootProps, RafflePickSlots, type RafflePickSlotsProps, RafflePickValue, type RafflePickValueProps, type RafflePickValue$1 as RafflePickValueType, RafflePickWheel, type RafflePickWheelProps, useRaffleContext };

package/dist/index.d.mts

@@ -94,6 +94,51 @@ interface RafflePickCountdownProps {
   /** Render-prop for fully custom output. Receives remaining seconds. */
   children?: (remaining: number) => ReactNode;
 }
+interface RafflePickWheelProps {
+  /**
+   * Segment labels. Defaults to the root's pool — `items`, or the `min`/`max`
+   * range. Pass this only to relabel segments; the winner is still chosen by
+   * the root, and label `i` maps to pool position `i`.
+   */
+  segments?: string[];
+  /** Outer diameter in px. Default `320`. */
+  size?: number;
+  /**
+   * Segment fill colors, cycled across segments. Defaults to a built-in
+   * 6-color palette. Adjacent segments never share a color as long as the
+   * palette length and segment count are not both even multiples.
+   */
+  colors?: string[];
+  /** Label text color. Default `'#fff'`. */
+  labelColor?: string;
+  /**
+   * Hide labels above this segment count — past it they overlap into noise.
+   * Colors and the landing still work. Default `40`. Set `Infinity` to force.
+   */
+  maxLabels?: number;
+  /** Landing animation duration in ms, from freeze to rest. Default `4200`. */
+  spinDuration?: number;
+  /** Full turns added before the landing angle, for a longer spin. Default `4`. */
+  turns?: number;
+  /** Idle/running rotation speed in ms per full turn. Default `1800`. */
+  spinInterval?: number;
+  /** Pointer position on the rim. Default `'top'`. */
+  pointer?: 'top' | 'right';
+  /** Hide the built-in pointer triangle to render your own. */
+  hidePointer?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Fires when the wheel physically comes to rest, with the winning value.
+   *
+   * Prefer this over the root's `onSelect` for anything the audience sees —
+   * a result banner, confetti, a sound. `onSelect` fires when the value is
+   * *committed*, which is the moment the landing animation **starts**, so
+   * reacting to it reveals the winner `spinDuration` ms before the wheel gets
+   * there.
+   */
+  onResult?: (value: RafflePickValue$1) => void;
+}
 //#endregion
 //#region src/components/RafflePick/RafflePick.d.ts
 declare function RafflePickRoot({
@@ -155,6 +200,23 @@ declare function RafflePickSlots({
   onResult
 }: RafflePickSlotsProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
+//#region src/components/RafflePick/RafflePickWheel.d.ts
+declare function RafflePickWheel({
+  segments,
+  size,
+  colors,
+  labelColor,
+  maxLabels,
+  spinDuration,
+  turns,
+  spinInterval,
+  pointer,
+  hidePointer,
+  className,
+  style,
+  onResult
+}: RafflePickWheelProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
 //#region src/utils/inertia.d.ts
 type RafflePickPhase = 'idle' | 'starting' | 'running' | 'settling' | 'frozen';
 //#endregion
@@ -175,8 +237,16 @@ interface RaffleContextValue {
   exhausted: boolean;
   /** Candidates left to draw. Equals the full pool size when `noRepeat` is off. */
   remaining: number;
+  /** Size of the draw pool: item count in items mode, `max - min + 1` in numeric mode. */
+  total: number;
   valueRef: RefObject<number>;
   displayValue: (index: number) => RafflePickValue$1;
+  /**
+   * Pool entry at a 0-based position, regardless of mode. `valueAt(0)` is the
+   * first item / `min`. Lets custom UIs enumerate the pool without knowing
+   * whether the root runs in items or numeric mode.
+   */
+  valueAt: (position: number) => RafflePickValue$1;
   subscribe: (fn: (value: number) => void) => () => void;
   start: () => void;
   freeze: () => void;
@@ -193,7 +263,8 @@ type RafflePickCompound = typeof RafflePickRoot & {
   Button: typeof RafflePickButton;
   Countdown: typeof RafflePickCountdown;
   Slots: typeof RafflePickSlots;
+  Wheel: typeof RafflePickWheel;
 };
 declare const RafflePick: RafflePickCompound;
 //#endregion
-export { type AnimationType, RaffleContext, type RaffleContextValue, RafflePick, RafflePickButton, type RafflePickButtonProps, RafflePickCountdown, type RafflePickCountdownProps, type RafflePickPhase, type RafflePickRootProps, RafflePickSlots, type RafflePickSlotsProps, RafflePickValue, type RafflePickValueProps, type RafflePickValue$1 as RafflePickValueType, useRaffleContext };
+export { type AnimationType, RaffleContext, type RaffleContextValue, RafflePick, RafflePickButton, type RafflePickButtonProps, RafflePickCountdown, type RafflePickCountdownProps, type RafflePickPhase, type RafflePickRootProps, RafflePickSlots, type RafflePickSlotsProps, RafflePickValue, type RafflePickValueProps, type RafflePickValue$1 as RafflePickValueType, RafflePickWheel, type RafflePickWheelProps, useRaffleContext };

package/dist/index.mjs

@@ -204,6 +204,11 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		const its = itemsRef.current;
 		return its && its.length > 0 ? its[index] : index;
 	}, []);
+	const valueAt = useCallback((position) => {
+		const its = itemsRef.current;
+		if (its && its.length > 0) return its[position];
+		return cycleMin + position;
+	}, [cycleMin]);
 	const valueToIndex = useCallback((value) => {
 		if (value === void 0) return void 0;
 		const its = itemsRef.current;
@@ -319,8 +324,10 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		noRepeat,
 		exhausted,
 		remaining,
+		total: totalCandidates,
 		valueRef,
 		displayValue,
+		valueAt,
 		subscribe,
 		start: guardedStart,
 		freeze,
@@ -339,7 +346,9 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		noRepeat,
 		exhausted,
 		remaining,
+		totalCandidates,
 		displayValue,
+		valueAt,
 		subscribe,
 		guardedStart,
 		freeze,
@@ -717,11 +726,292 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 	});
 }
 //#endregion
+//#region src/components/RafflePick/RafflePickWheel.tsx
+const DEFAULT_COLORS = [
+	"#7c1d29",
+	"#d4a04a",
+	"#2f4858",
+	"#a83b2c",
+	"#ecc878",
+	"#4a0f18"
+];
+const VIEWBOX = 100;
+const CENTER = VIEWBOX / 2;
+const RADIUS = 48;
+const LABEL_RADIUS = RADIUS * .66;
+const prefersReducedMotion = () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+/** Point on the wheel rim at `deg`, measured clockwise from 12 o'clock. */
+const rimPoint = (deg, radius) => {
+	const rad = (deg - 90) * Math.PI / 180;
+	return {
+		x: CENTER + radius * Math.cos(rad),
+		y: CENTER + radius * Math.sin(rad)
+	};
+};
+const segmentPath = (index, total) => {
+	const sweep = 360 / total;
+	const a0 = index * sweep;
+	const a1 = a0 + sweep;
+	const p0 = rimPoint(a0, RADIUS);
+	const p1 = rimPoint(a1, RADIUS);
+	const largeArc = sweep > 180 ? 1 : 0;
+	return `M ${CENTER} ${CENTER} L ${p0.x} ${p0.y} A ${RADIUS} ${RADIUS} 0 ${largeArc} 1 ${p1.x} ${p1.y} Z`;
+};
+/**
+* Rotation, in degrees, that parks the centre of segment `position` under a
+* pointer sitting at `pointerDeg` clockwise from 12 o'clock.
+*/
+const restAngleFor = (position, total, pointerDeg) => pointerDeg - (position + .5) * (360 / total);
+/**
+* Next rotation past `from` that lands on `position`, after at least `turns`
+* more full revolutions. Always forward, so the wheel never visibly rewinds.
+*/
+const landingAngle = (from, position, total, turns, pointerDeg) => {
+	const base = from + turns * 360;
+	return base + ((restAngleFor(position, total, pointerDeg) - base) % 360 + 360) % 360;
+};
+function RafflePickWheel({ segments, size = 320, colors = DEFAULT_COLORS, labelColor = "#fff", maxLabels = 40, spinDuration = 4200, turns = 4, spinInterval = 1800, pointer = "top", hidePointer = false, className, style, onResult }) {
+	const { phase, total, valueAt, valueRef, hasItems, displayed } = useRaffleContext("RafflePick.Wheel");
+	const count = segments?.length ?? total;
+	const safeCount = Math.max(1, count);
+	const labels = useMemo(() => {
+		if (segments) return segments;
+		return Array.from({ length: safeCount }, (_, i) => String(valueAt(i)));
+	}, [
+		segments,
+		safeCount,
+		valueAt
+	]);
+	const indexOffset = useMemo(() => {
+		if (hasItems || segments) return 0;
+		const first = valueAt(0);
+		return typeof first === "number" ? first : 0;
+	}, [
+		hasItems,
+		segments,
+		valueAt
+	]);
+	const pointerDeg = pointer === "right" ? 90 : 0;
+	const wheelRef = useRef(null);
+	const rootRef = useRef(null);
+	const liveRef = useRef(null);
+	const rotationRef = useRef(0);
+	const rafRef = useRef(null);
+	const lastFrameRef = useRef(0);
+	const setResting = useCallback((rest, announce) => {
+		const root = rootRef.current;
+		if (root) if (rest) root.setAttribute("data-resting", "");
+		else root.removeAttribute("data-resting");
+		const live = liveRef.current;
+		if (live) live.textContent = rest && announce !== void 0 ? announce : "";
+	}, []);
+	const onResultRef = useRef(onResult);
+	useEffect(() => {
+		onResultRef.current = onResult;
+	});
+	const write = useCallback((deg) => {
+		const node = wheelRef.current;
+		if (node) node.style.transform = `rotate(${deg}deg)`;
+	}, []);
+	const spinning = phase === "starting" || phase === "running" || phase === "settling";
+	useEffect(() => {
+		if (!spinning) return;
+		setResting(false);
+		if (prefersReducedMotion()) return;
+		const node = wheelRef.current;
+		if (node) node.style.transition = "none";
+		lastFrameRef.current = 0;
+		const frame = (now) => {
+			const last = lastFrameRef.current || now;
+			lastFrameRef.current = now;
+			rotationRef.current += (now - last) / Math.max(200, spinInterval) * 360;
+			write(rotationRef.current);
+			rafRef.current = requestAnimationFrame(frame);
+		};
+		rafRef.current = requestAnimationFrame(frame);
+		return () => {
+			if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+			rafRef.current = null;
+		};
+	}, [
+		spinning,
+		spinInterval,
+		write,
+		setResting
+	]);
+	useEffect(() => {
+		if (phase !== "frozen") return;
+		const position = Math.min(safeCount - 1, Math.max(0, valueRef.current - indexOffset));
+		const node = wheelRef.current;
+		if (prefersReducedMotion() || !node) {
+			rotationRef.current = restAngleFor(position, safeCount, pointerDeg);
+			write(rotationRef.current);
+			setResting(true, String(displayed));
+			onResultRef.current?.(displayed);
+			return;
+		}
+		const target = landingAngle(rotationRef.current, position, safeCount, Math.max(0, turns), pointerDeg);
+		rotationRef.current = target;
+		node.style.transition = `transform ${spinDuration}ms cubic-bezier(0.16, 1, 0.3, 1)`;
+		node.getBoundingClientRect();
+		write(target);
+		let done = false;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			setResting(true, String(displayed));
+			onResultRef.current?.(displayed);
+		};
+		node.addEventListener("transitionend", finish, { once: true });
+		const fallback = setTimeout(finish, spinDuration + 120);
+		return () => {
+			node.removeEventListener("transitionend", finish);
+			clearTimeout(fallback);
+		};
+	}, [
+		phase,
+		safeCount,
+		indexOffset,
+		turns,
+		spinDuration,
+		write,
+		valueRef,
+		displayed,
+		pointerDeg,
+		setResting
+	]);
+	useEffect(() => {
+		if (phase !== "idle") return;
+		const position = Math.min(safeCount - 1, Math.max(0, valueRef.current - indexOffset));
+		const node = wheelRef.current;
+		if (node) node.style.transition = "none";
+		rotationRef.current = restAngleFor(position, safeCount, pointerDeg);
+		write(rotationRef.current);
+		setResting(true);
+	}, [
+		phase,
+		safeCount,
+		indexOffset,
+		write,
+		valueRef,
+		pointerDeg,
+		setResting
+	]);
+	const showLabels = safeCount <= maxLabels;
+	const fontSize = Math.max(2.2, Math.min(5, 42 / safeCount + 1.6));
+	const paths = useMemo(() => Array.from({ length: safeCount }, (_, i) => ({
+		d: safeCount === 1 ? "" : segmentPath(i, safeCount),
+		fill: colors[i % colors.length],
+		mid: (i + .5) * (360 / safeCount)
+	})), [safeCount, colors]);
+	const cls = joinClassNames("rrp-wheel", className);
+	const pointerStyle = pointer === "right" ? {
+		position: "absolute",
+		top: "50%",
+		right: -2,
+		width: 0,
+		height: 0,
+		transform: "translateY(-50%)",
+		borderTop: `${size * .045}px solid transparent`,
+		borderBottom: `${size * .045}px solid transparent`,
+		borderRight: `${size * .09}px solid currentColor`
+	} : {
+		position: "absolute",
+		left: "50%",
+		top: -2,
+		width: 0,
+		height: 0,
+		transform: "translateX(-50%)",
+		borderLeft: `${size * .045}px solid transparent`,
+		borderRight: `${size * .045}px solid transparent`,
+		borderTop: `${size * .09}px solid currentColor`
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		ref: rootRef,
+		className: cls,
+		style: {
+			position: "relative",
+			display: "inline-block",
+			lineHeight: 0,
+			...style,
+			width: size,
+			height: size
+		},
+		"data-phase": phase,
+		"data-pointer": pointer,
+		"data-resting": "",
+		children: [
+			/* @__PURE__ */ jsxs("svg", {
+				ref: wheelRef,
+				className: "rrp-wheel__disc",
+				style: {
+					display: "block",
+					transformOrigin: "50% 50%",
+					willChange: "transform"
+				},
+				viewBox: `0 0 ${VIEWBOX} ${VIEWBOX}`,
+				width: size,
+				height: size,
+				role: "img",
+				"aria-label": `Wheel with ${safeCount} segments`,
+				children: [safeCount === 1 ? /* @__PURE__ */ jsx("circle", {
+					cx: CENTER,
+					cy: CENTER,
+					r: RADIUS,
+					fill: paths[0].fill
+				}) : paths.map((p, i) => /* @__PURE__ */ jsx("path", {
+					d: p.d,
+					fill: p.fill,
+					stroke: "rgba(0,0,0,0.14)",
+					strokeWidth: .3
+				}, i)), showLabels && paths.map((p, i) => {
+					const pt = rimPoint(p.mid, LABEL_RADIUS);
+					const rotate = p.mid > 180 ? p.mid + 90 : p.mid - 90;
+					return /* @__PURE__ */ jsx("text", {
+						x: pt.x,
+						y: pt.y,
+						fill: labelColor,
+						fontSize,
+						fontWeight: 600,
+						textAnchor: "middle",
+						dominantBaseline: "middle",
+						transform: `rotate(${rotate} ${pt.x} ${pt.y})`,
+						style: {
+							pointerEvents: "none",
+							userSelect: "none"
+						},
+						children: labels[i]
+					}, i);
+				})]
+			}),
+			!hidePointer && /* @__PURE__ */ jsx("span", {
+				className: "rrp-wheel__pointer",
+				style: pointerStyle,
+				"aria-hidden": "true"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				ref: liveRef,
+				role: "status",
+				"aria-live": "polite",
+				style: {
+					position: "absolute",
+					width: 1,
+					height: 1,
+					overflow: "hidden",
+					clip: "rect(0, 0, 0, 0)",
+					whiteSpace: "nowrap"
+				}
+			})
+		]
+	});
+}
+//#endregion
 //#region src/components/RafflePick/index.ts
 const RafflePick = RafflePickRoot;
 RafflePick.Value = RafflePickValue;
 RafflePick.Button = RafflePickButton;
 RafflePick.Countdown = RafflePickCountdown;
 RafflePick.Slots = RafflePickSlots;
+RafflePick.Wheel = RafflePickWheel;
 //#endregion
-export { RaffleContext, RafflePick, RafflePickButton, RafflePickCountdown, RafflePickSlots, RafflePickValue, useRaffleContext };
+export { RaffleContext, RafflePick, RafflePickButton, RafflePickCountdown, RafflePickSlots, RafflePickValue, RafflePickWheel, useRaffleContext };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-raffle-picker",
-  "version": "0.3.1",
-  "description": "Headless React raffle picker for giveaways, winner draws, countdowns, and slot-machine UIs.",
+  "version": "0.4.0",
+  "description": "React random picker: draw a random winner or number with slot-machine, reel and countdown animations. Headless, typed, zero-dependency.",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -61,18 +61,28 @@
   },
   "keywords": [
     "react",
-    "raffle",
-    "giveaway",
-    "winner",
-    "picker",
     "random-picker",
-    "draw",
+    "random-name-picker",
+    "name-picker",
+    "winner-picker",
+    "random-winner",
+    "giveaway",
+    "giveaway-picker",
+    "prize-draw",
+    "raffle",
+    "raffle-picker",
     "lottery",
     "slot-machine",
+    "slot-machine-react",
+    "reel",
+    "number-picker",
+    "random-number",
     "countdown",
     "headless",
+    "headless-ui",
     "compound-components",
-    "react-component"
+    "react-component",
+    "typescript"
   ],
   "author": "Kirilinsky (https://github.com/kirilinsky)",
   "license": "MIT",
@@ -115,4 +125,4 @@
   "volta": {
     "node": "22.12.0"
   }
-}
+}