react-raffle-picker 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 
   <h1>react-raffle-picker</h1>
 
-  <p><strong>Tiny raffle engine. Big winner energy.</strong></p>
+  <p><strong>React like you just won. The raffle picker your UI deserves.</strong></p>
 
   <p>
     <a href="https://react-raffle-one.vercel.app/">Live demo</a>
@@ -75,6 +75,21 @@ import { RafflePick } from 'react-raffle-picker'
 </RafflePick>
 ```
 
+### Styles
+
+The library is headless — no global stylesheet is required for `Value`, `Button`, or `Countdown`. You bring your own CSS.
+
+For the **slot reel** (`<RafflePick.Slots>`), a minimal stylesheet *is* required to make the column animate. Two ways to load it:
+
+1. **Auto-injected at runtime** — `<RafflePick.Slots>` injects a `<style data-rrp-slot-base>` tag into `document.head` on first mount. No action needed in CSR apps.
+2. **Static import** (recommended for SSR / strict CSP / full control):
+
+   ```ts
+   import 'react-raffle-picker/styles.css'
+   ```
+
+   This file also includes opt-in keyframes for `<RafflePick.Value animation="roll|fade|blur|reel" />`. Override or replace any selector in your own CSS.
+
 ## Components
 
 ### `<RafflePick>` (root)
@@ -89,6 +104,8 @@ 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.                       |
+| `initialValue` | `number \| string`        | —          | Starting display before first run. Number for `min`/`max` mode, string for `items` mode. |
+| `finalValue`   | `number \| string`        | —          | Forces settle to land on this value. Cycle still appears random; only final freeze is rigged. |
 | `onSelect`   | `(value) => void`           | —          | Fires once per round on freeze.               |
 | `as`         | `ElementType`               | `'div'`    | Wrapper tag.                                  |
 | `className`  | `string`                    | —          | Wrapper class.                                |
@@ -166,6 +183,23 @@ Independent multi-reel slot machine. Each reel ticks on its own and stops with a
 </RafflePick>
 ```
 
+### Rigged draw with predetermined winner
+
+`finalValue` lands the freeze on a specific value while the cycle still looks random — useful for staged demos, scripted reveals, or showing a known winner.
+
+```tsx
+<RafflePick
+  items={['Alice', 'Bob', 'Carol']}
+  initialValue="Alice"
+  finalValue="Bob"
+  autoStart={false}
+  onSelect={(winner) => console.log(winner)} // always 'Bob'
+>
+  <RafflePick.Value animation="reel" />
+  <RafflePick.Button startLabel="Draw" stopLabel="Reveal" />
+</RafflePick>
+```
+
 ### Slot machine with custom result handler
 
 ```tsx

package/dist/index.cjs

@@ -172,7 +172,7 @@ const useRaffleContext = (componentName) => {
 };
 //#endregion
 //#region src/components/RafflePick/RafflePick.tsx
-function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = true, inertia = false, autoStart = true, onSelect, as = "div", className, style, children }) {
+function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = true, inertia = false, autoStart = true, initialValue, finalValue, onSelect, as = "div", className, style, children }) {
 	const itemCount = items?.length ?? 0;
 	const hasItems = itemCount > 0;
 	const cycleMin = hasItems ? 0 : min;
@@ -186,7 +186,33 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		const its = itemsRef.current;
 		return its && its.length > 0 ? its[index] : index;
 	}, []);
-	const [displayed, setDisplayed] = (0, react.useState)(() => items && items.length > 0 ? items[cycleMin] : cycleMin);
+	const valueToIndex = (0, react.useCallback)((value) => {
+		if (value === void 0) return void 0;
+		const its = itemsRef.current;
+		if (its && its.length > 0) {
+			const i = its.indexOf(String(value));
+			return i >= 0 ? i : void 0;
+		}
+		return typeof value === "number" ? value : void 0;
+	}, []);
+	const initialIndex = (() => {
+		if (initialValue === void 0) return cycleMin;
+		if (items && items.length > 0) {
+			const i = items.indexOf(String(initialValue));
+			return i >= 0 ? i : cycleMin;
+		}
+		return typeof initialValue === "number" ? initialValue : cycleMin;
+	})();
+	const [displayed, setDisplayed] = (0, react.useState)(() => {
+		if (initialValue !== void 0) {
+			const its = items;
+			if (its && its.length > 0) {
+				const i = its.indexOf(String(initialValue));
+				if (i >= 0) return its[i];
+			} else if (typeof initialValue === "number") return initialValue;
+		}
+		return items && items.length > 0 ? items[cycleMin] : cycleMin;
+	});
 	const subscribersRef = (0, react.useRef)(/* @__PURE__ */ new Set());
 	const subscribe = (0, react.useCallback)((fn) => {
 		subscribersRef.current.add(fn);
@@ -197,12 +223,22 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 	const onTick = (0, react.useCallback)((value) => {
 		subscribersRef.current.forEach((fn) => fn(value));
 	}, []);
-	const valueRef = (0, react.useRef)(cycleMin);
+	const valueRef = (0, react.useRef)(initialIndex);
+	const finalValueRef = (0, react.useRef)(finalValue);
+	(0, react.useEffect)(() => {
+		finalValueRef.current = finalValue;
+	}, [finalValue]);
 	const { phase, step, start, freeze, reset } = useRafflePhase(inertia, initialPhase, (0, react.useCallback)(() => {
+		const forced = valueToIndex(finalValueRef.current);
+		if (forced !== void 0) valueRef.current = forced;
 		const v = displayValue(valueRef.current);
 		setDisplayed(v);
 		onSelect?.(v);
-	}, [displayValue, onSelect]));
+	}, [
+		displayValue,
+		onSelect,
+		valueToIndex
+	]));
 	const multiplier = getInertiaMultiplier(phase, step, inertia);
 	const cycleInterval = Math.round(Math.max(50, interval) * multiplier);
 	useNumberCycle({
@@ -221,7 +257,7 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		cycleInterval,
 		inertia,
 		hasItems,
-		initialIndex: cycleMin,
+		initialIndex,
 		valueRef,
 		displayValue,
 		subscribe,
@@ -235,7 +271,7 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		cycleInterval,
 		inertia,
 		hasItems,
-		cycleMin,
+		initialIndex,
 		displayValue,
 		subscribe,
 		start,
@@ -388,6 +424,27 @@ function CountdownRunning({ seconds, className, style, children }) {
 //#endregion
 //#region src/components/RafflePick/RafflePickSlots.tsx
 const pickRandom = (pool) => pool[Math.floor(Math.random() * pool.length)] ?? "";
+const SLOT_BASE_CSS = `
+.rrp-slot{display:inline-block;overflow:hidden;height:1em;line-height:1em;vertical-align:baseline}
+.rrp-slot__col{display:flex;flex-direction:column;transform:translateY(-1em);animation:rrp-slot-reel var(--rrp-tick,80ms) linear infinite}
+.rrp-slot__cell{display:block;height:1em;line-height:1em}
+.rrp-slot[data-stopped] .rrp-slot__col{animation:none;transform:translateY(-1em)}
+@keyframes rrp-slot-reel{from{transform:translateY(-1em)}to{transform:translateY(-2em)}}
+`;
+let slotStylesInjected = false;
+const injectSlotStyles = () => {
+	if (slotStylesInjected) return;
+	if (typeof document === "undefined") return;
+	if (document.querySelector("style[data-rrp-slot-base]")) {
+		slotStylesInjected = true;
+		return;
+	}
+	const tag = document.createElement("style");
+	tag.setAttribute("data-rrp-slot-base", "");
+	tag.textContent = SLOT_BASE_CSS;
+	document.head.appendChild(tag);
+	slotStylesInjected = true;
+};
 const makeRefs = () => ({
 	root: null,
 	col: null,
@@ -398,6 +455,7 @@ const makeRefs = () => ({
 	stopped: false
 });
 function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80, staggerMs = 220, className, slotClassName, style, slotStyle, onResult }) {
+	injectSlotStyles();
 	const { phase } = useRaffleContext("RafflePick.Slots");
 	const slotsRef = (0, react.useRef)([]);
 	const stopTimersRef = (0, react.useRef)([]);

package/dist/index.d.cts

@@ -13,6 +13,10 @@ interface RafflePickRootProps {
   random?: boolean;
   inertia?: boolean;
   autoStart?: boolean;
+  /** Value shown before first run. Number in min/max mode, string in items mode. */
+  initialValue?: RafflePickValue$1;
+  /** When set, settle always lands on this value while cycle still appears random. */
+  finalValue?: RafflePickValue$1;
   onSelect?: (value: RafflePickValue$1) => void;
   as?: ElementType;
   className?: string;
@@ -71,6 +75,8 @@ declare function RafflePickRoot({
   random,
   inertia,
   autoStart,
+  initialValue,
+  finalValue,
   onSelect,
   as,
   className,

package/dist/index.d.mts

@@ -13,6 +13,10 @@ interface RafflePickRootProps {
   random?: boolean;
   inertia?: boolean;
   autoStart?: boolean;
+  /** Value shown before first run. Number in min/max mode, string in items mode. */
+  initialValue?: RafflePickValue$1;
+  /** When set, settle always lands on this value while cycle still appears random. */
+  finalValue?: RafflePickValue$1;
   onSelect?: (value: RafflePickValue$1) => void;
   as?: ElementType;
   className?: string;
@@ -71,6 +75,8 @@ declare function RafflePickRoot({
   random,
   inertia,
   autoStart,
+  initialValue,
+  finalValue,
   onSelect,
   as,
   className,

package/dist/index.mjs

@@ -171,7 +171,7 @@ const useRaffleContext = (componentName) => {
 };
 //#endregion
 //#region src/components/RafflePick/RafflePick.tsx
-function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = true, inertia = false, autoStart = true, onSelect, as = "div", className, style, children }) {
+function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = true, inertia = false, autoStart = true, initialValue, finalValue, onSelect, as = "div", className, style, children }) {
 	const itemCount = items?.length ?? 0;
 	const hasItems = itemCount > 0;
 	const cycleMin = hasItems ? 0 : min;
@@ -185,7 +185,33 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		const its = itemsRef.current;
 		return its && its.length > 0 ? its[index] : index;
 	}, []);
-	const [displayed, setDisplayed] = useState(() => items && items.length > 0 ? items[cycleMin] : cycleMin);
+	const valueToIndex = useCallback((value) => {
+		if (value === void 0) return void 0;
+		const its = itemsRef.current;
+		if (its && its.length > 0) {
+			const i = its.indexOf(String(value));
+			return i >= 0 ? i : void 0;
+		}
+		return typeof value === "number" ? value : void 0;
+	}, []);
+	const initialIndex = (() => {
+		if (initialValue === void 0) return cycleMin;
+		if (items && items.length > 0) {
+			const i = items.indexOf(String(initialValue));
+			return i >= 0 ? i : cycleMin;
+		}
+		return typeof initialValue === "number" ? initialValue : cycleMin;
+	})();
+	const [displayed, setDisplayed] = useState(() => {
+		if (initialValue !== void 0) {
+			const its = items;
+			if (its && its.length > 0) {
+				const i = its.indexOf(String(initialValue));
+				if (i >= 0) return its[i];
+			} else if (typeof initialValue === "number") return initialValue;
+		}
+		return items && items.length > 0 ? items[cycleMin] : cycleMin;
+	});
 	const subscribersRef = useRef(/* @__PURE__ */ new Set());
 	const subscribe = useCallback((fn) => {
 		subscribersRef.current.add(fn);
@@ -196,12 +222,22 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 	const onTick = useCallback((value) => {
 		subscribersRef.current.forEach((fn) => fn(value));
 	}, []);
-	const valueRef = useRef(cycleMin);
+	const valueRef = useRef(initialIndex);
+	const finalValueRef = useRef(finalValue);
+	useEffect(() => {
+		finalValueRef.current = finalValue;
+	}, [finalValue]);
 	const { phase, step, start, freeze, reset } = useRafflePhase(inertia, initialPhase, useCallback(() => {
+		const forced = valueToIndex(finalValueRef.current);
+		if (forced !== void 0) valueRef.current = forced;
 		const v = displayValue(valueRef.current);
 		setDisplayed(v);
 		onSelect?.(v);
-	}, [displayValue, onSelect]));
+	}, [
+		displayValue,
+		onSelect,
+		valueToIndex
+	]));
 	const multiplier = getInertiaMultiplier(phase, step, inertia);
 	const cycleInterval = Math.round(Math.max(50, interval) * multiplier);
 	useNumberCycle({
@@ -220,7 +256,7 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		cycleInterval,
 		inertia,
 		hasItems,
-		initialIndex: cycleMin,
+		initialIndex,
 		valueRef,
 		displayValue,
 		subscribe,
@@ -234,7 +270,7 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		cycleInterval,
 		inertia,
 		hasItems,
-		cycleMin,
+		initialIndex,
 		displayValue,
 		subscribe,
 		start,
@@ -387,6 +423,27 @@ function CountdownRunning({ seconds, className, style, children }) {
 //#endregion
 //#region src/components/RafflePick/RafflePickSlots.tsx
 const pickRandom = (pool) => pool[Math.floor(Math.random() * pool.length)] ?? "";
+const SLOT_BASE_CSS = `
+.rrp-slot{display:inline-block;overflow:hidden;height:1em;line-height:1em;vertical-align:baseline}
+.rrp-slot__col{display:flex;flex-direction:column;transform:translateY(-1em);animation:rrp-slot-reel var(--rrp-tick,80ms) linear infinite}
+.rrp-slot__cell{display:block;height:1em;line-height:1em}
+.rrp-slot[data-stopped] .rrp-slot__col{animation:none;transform:translateY(-1em)}
+@keyframes rrp-slot-reel{from{transform:translateY(-1em)}to{transform:translateY(-2em)}}
+`;
+let slotStylesInjected = false;
+const injectSlotStyles = () => {
+	if (slotStylesInjected) return;
+	if (typeof document === "undefined") return;
+	if (document.querySelector("style[data-rrp-slot-base]")) {
+		slotStylesInjected = true;
+		return;
+	}
+	const tag = document.createElement("style");
+	tag.setAttribute("data-rrp-slot-base", "");
+	tag.textContent = SLOT_BASE_CSS;
+	document.head.appendChild(tag);
+	slotStylesInjected = true;
+};
 const makeRefs = () => ({
 	root: null,
 	col: null,
@@ -397,6 +454,7 @@ const makeRefs = () => ({
 	stopped: false
 });
 function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80, staggerMs = 220, className, slotClassName, style, slotStyle, onResult }) {
+	injectSlotStyles();
 	const { phase } = useRaffleContext("RafflePick.Slots");
 	const slotsRef = useRef([]);
 	const stopTimersRef = useRef([]);

package/dist/styles.css

@@ -0,0 +1,63 @@
+/* react-raffle-picker — base styles */
+/* Optional. Slot reel animation is also auto-injected at runtime. */
+/* Import via: import 'react-raffle-picker/styles.css' */
+
+.rrp-slot {
+  display: inline-block;
+  overflow: hidden;
+  height: 1em;
+  line-height: 1em;
+  vertical-align: baseline;
+}
+.rrp-slot__col {
+  display: flex;
+  flex-direction: column;
+  transform: translateY(-1em);
+  animation: rrp-slot-reel var(--rrp-tick, 80ms) linear infinite;
+}
+.rrp-slot__cell {
+  display: block;
+  height: 1em;
+  line-height: 1em;
+}
+.rrp-slot[data-stopped] .rrp-slot__col {
+  animation: none;
+  transform: translateY(-1em);
+}
+@keyframes rrp-slot-reel {
+  from { transform: translateY(-1em); }
+  to   { transform: translateY(-2em); }
+}
+
+/* Value animations: opt-in via <RafflePick.Value animation="..." /> */
+.rrp-value {
+  display: inline-block;
+}
+.rrp-value[data-animation='roll'][data-phase='running'] {
+  animation: rrp-value-roll var(--rrp-tick, 100ms) linear;
+}
+.rrp-value[data-animation='fade'][data-phase='running'] {
+  animation: rrp-value-fade var(--rrp-tick, 100ms) linear;
+}
+.rrp-value[data-animation='blur'][data-phase='running'] {
+  animation: rrp-value-blur var(--rrp-tick, 100ms) linear;
+}
+.rrp-value[data-animation='reel'][data-phase='running'] {
+  animation: rrp-value-reel var(--rrp-tick, 100ms) linear;
+}
+@keyframes rrp-value-roll {
+  from { transform: translateY(-0.4em); opacity: 0.4; }
+  to   { transform: translateY(0); opacity: 1; }
+}
+@keyframes rrp-value-fade {
+  from { opacity: 0.2; }
+  to   { opacity: 1; }
+}
+@keyframes rrp-value-blur {
+  from { filter: blur(4px); }
+  to   { filter: blur(0); }
+}
+@keyframes rrp-value-reel {
+  from { transform: translateY(-1em); opacity: 0; }
+  to   { transform: translateY(0); opacity: 1; }
+}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "react-raffle-picker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless React raffle picker for giveaways, winner draws, countdowns, and slot-machine UIs.",
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -16,9 +21,12 @@
       "require": "./dist/index.cjs",
       "default": "./dist/index.mjs"
     },
+    "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "files": [
     "dist"
   ],
@@ -31,7 +39,7 @@
   },
   "homepage": "https://react-raffle-one.vercel.app/",
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && cp src/styles.css dist/styles.css",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
@@ -45,7 +53,7 @@
     "build-storybook": "storybook build",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "changeset publish --provenance"
+    "release": "changeset publish"
   },
   "peerDependencies": {
     "react": ">=17",
@@ -68,9 +76,6 @@
   ],
   "author": "Kirilinsky (https://github.com/kirilinsky)",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "engines": {
     "node": ">=18"
   },
@@ -107,4 +112,4 @@
     "vite": "^8.0.8",
     "vitest": "^4.1.4"
   }
-}
+}