react-raffle-picker 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="https://i.ibb.co/k2MRQCqT/logo-nbg.png" alt="react-raffle-picker logo placeholder" width="160" />
+  <img src="https://i.ibb.co/yB50hJTv/logo-nbg.png" alt="react-raffle-picker logo placeholder" width="160" />
 
   <h1>react-raffle-picker</h1>
 
@@ -69,7 +69,7 @@ This means:
 ```tsx
 import { RafflePick } from 'react-raffle-picker'
 
-<RafflePick min={1} max={100} interval={100} inertia onSelect={(v) => console.log(v)}>
+;<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" />
 </RafflePick>
@@ -79,7 +79,7 @@ import { RafflePick } from 'react-raffle-picker'
 
 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:
+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):
@@ -96,21 +96,21 @@ For the **slot reel** (`<RafflePick.Slots>`), a minimal stylesheet *is* required
 
 Provides context. Renders an optional wrapper element (`as` prop, default `'div'`).
 
-| Prop         | Type                        | Default    | Notes                                         |
-| ------------ | --------------------------- | ---------- | --------------------------------------------- |
-| `min`, `max` | `number`                    | `1`, `100` | Numeric range. Ignored if `items` provided.   |
-| `items`      | `string[]`                  | —          | Switches to item mode (cycles through names). |
-| `interval`   | `number` (ms, clamped ≥ 50) | `100`      | Tick speed.                                   |
-| `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.                                |
-| `style`      | `CSSProperties`             | —          | Wrapper style.                                |
-| `children`   | `ReactNode`                 | —          | Sub-components.                               |
+| Prop           | Type                        | Default    | Notes                                                                                                                                                                    |
+| -------------- | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `min`, `max`   | `number`                    | `1`, `100` | Numeric range. Ignored if `items` provided.                                                                                                                              |
+| `items`        | `string[]`                  | —          | Switches to item mode (cycles through names).                                                                                                                            |
+| `interval`     | `number` (ms, clamped ≥ 50) | `100`      | Tick speed.                                                                                                                                                              |
+| `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. 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.                                                                                                                                          |
+| `as`           | `ElementType`               | `'div'`    | Wrapper tag.                                                                                                                                                             |
+| `className`    | `string`                    | —          | Wrapper class.                                                                                                                                                           |
+| `style`        | `CSSProperties`             | —          | Wrapper style.                                                                                                                                                           |
+| `children`     | `ReactNode`                 | —          | Sub-components.                                                                                                                                                          |
 
 ### `<RafflePick.Value>`
 
@@ -153,6 +153,8 @@ Schedules auto-freeze after `seconds`. Renders an SVG ring + numeric label by de
 
 Independent multi-reel slot machine. Each reel ticks on its own and stops with a stagger.
 
+`initialValue` (root prop) seeds reels char-by-char before the first run. `finalValue` rigs the freeze so each reel lands on the corresponding character — useful for predetermined winners or scripted demos.
+
 | Prop                                               | Type                       | Default        | Notes                                        |
 | -------------------------------------------------- | -------------------------- | -------------- | -------------------------------------------- |
 | `length`                                           | `number`                   | `3`            | Number of reels.                             |

package/dist/index.cjs

@@ -258,6 +258,8 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		inertia,
 		hasItems,
 		initialIndex,
+		initialValue,
+		finalValue,
 		valueRef,
 		displayValue,
 		subscribe,
@@ -272,6 +274,8 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		inertia,
 		hasItems,
 		initialIndex,
+		initialValue,
+		finalValue,
 		displayValue,
 		subscribe,
 		start,
@@ -425,25 +429,26 @@ function CountdownRunning({ seconds, className, style, children }) {
 //#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)}}
+.rrp-slot{display:inline-block;position:relative;overflow:hidden;vertical-align:baseline}
+.rrp-slot__col{position:absolute;top:0;left:0;right:0;height:300%;transform:translate3d(0,-33.3333%,0);animation:rrp-slot-reel var(--rrp-tick,80ms) linear infinite;will-change:transform}
+.rrp-slot__cell{height:33.3333%;display:grid;place-items:center;padding:0;margin:0;box-sizing:border-box;text-align:center}
+.rrp-slot[data-stopped] .rrp-slot__col{animation:none;transform:translate3d(0,-33.3333%,0)}
+@keyframes rrp-slot-reel{from{transform:translate3d(0,-33.3333%,0)}to{transform:translate3d(0,-66.6666%,0)}}
 `;
-let slotStylesInjected = false;
+const SLOT_STYLES_VERSION = "4";
 const injectSlotStyles = () => {
-	if (slotStylesInjected) return;
 	if (typeof document === "undefined") return;
-	if (document.querySelector("style[data-rrp-slot-base]")) {
-		slotStylesInjected = true;
+	const existing = document.querySelector("style[data-rrp-slot-base]");
+	if (existing) {
+		if (existing.getAttribute("data-rrp-slot-base") === SLOT_STYLES_VERSION) return;
+		existing.textContent = SLOT_BASE_CSS;
+		existing.setAttribute("data-rrp-slot-base", SLOT_STYLES_VERSION);
 		return;
 	}
 	const tag = document.createElement("style");
-	tag.setAttribute("data-rrp-slot-base", "");
+	tag.setAttribute("data-rrp-slot-base", SLOT_STYLES_VERSION);
 	tag.textContent = SLOT_BASE_CSS;
 	document.head.appendChild(tag);
-	slotStylesInjected = true;
 };
 const makeRefs = () => ({
 	root: null,
@@ -456,7 +461,19 @@ const makeRefs = () => ({
 });
 function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80, staggerMs = 220, className, slotClassName, style, slotStyle, onResult }) {
 	injectSlotStyles();
-	const { phase } = useRaffleContext("RafflePick.Slots");
+	const { phase, initialValue, finalValue } = useRaffleContext("RafflePick.Slots");
+	const initialChars = (0, react.useMemo)(() => {
+		const seed = typeof initialValue === "string" ? initialValue : "";
+		return Array.from({ length }, (_, i) => seed[i] ?? "");
+	}, [initialValue, length]);
+	const finalChars = (0, react.useMemo)(() => {
+		if (typeof finalValue !== "string") return null;
+		return Array.from({ length }, (_, i) => finalValue[i] ?? "");
+	}, [finalValue, length]);
+	const finalCharsRef = (0, react.useRef)(finalChars);
+	(0, react.useEffect)(() => {
+		finalCharsRef.current = finalChars;
+	}, [finalChars]);
 	const slotsRef = (0, react.useRef)([]);
 	const stopTimersRef = (0, react.useRef)([]);
 	const finalRef = (0, react.useRef)([]);
@@ -514,6 +531,8 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 		for (let i = 0; i < length; i++) {
 			const id = setTimeout(() => {
 				const s = slotsRef.current[i];
+				const forced = finalCharsRef.current?.[i];
+				if (forced) writeSlot(s, s.currChar, forced, forced);
 				s.stopped = true;
 				if (s.root) s.root.setAttribute("data-stopped", "");
 				finalRef.current[i] = s.currChar;
@@ -529,17 +548,19 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 	]);
 	(0, react.useEffect)(() => {
 		if (phase !== "idle") return;
-		const c = pool[0] ?? "";
+		const fallback = pool[0] ?? "";
 		for (let i = 0; i < length; i++) {
 			const s = slotsRef.current[i];
+			const c = initialChars[i] || fallback;
 			s.stopped = true;
 			writeSlot(s, c, c, c);
-			if (s.root) s.root.removeAttribute("data-stopped");
+			if (s.root) s.root.setAttribute("data-stopped", "");
 		}
 	}, [
 		phase,
 		length,
-		pool
+		pool,
+		initialChars
 	]);
 	const cls = (0, react.useMemo)(() => joinClassNames("rrp-slots", className), [className]);
 	const slotCls = (0, react.useMemo)(() => joinClassNames("rrp-slot", slotClassName), [slotClassName]);

package/dist/index.d.cts

@@ -135,6 +135,8 @@ interface RaffleContextValue {
   inertia: boolean;
   hasItems: boolean;
   initialIndex: number;
+  initialValue?: RafflePickValue$1;
+  finalValue?: RafflePickValue$1;
   valueRef: RefObject<number>;
   displayValue: (index: number) => RafflePickValue$1;
   subscribe: (fn: (value: number) => void) => () => void;

package/dist/index.d.mts

@@ -135,6 +135,8 @@ interface RaffleContextValue {
   inertia: boolean;
   hasItems: boolean;
   initialIndex: number;
+  initialValue?: RafflePickValue$1;
+  finalValue?: RafflePickValue$1;
   valueRef: RefObject<number>;
   displayValue: (index: number) => RafflePickValue$1;
   subscribe: (fn: (value: number) => void) => () => void;

package/dist/index.mjs

@@ -257,6 +257,8 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		inertia,
 		hasItems,
 		initialIndex,
+		initialValue,
+		finalValue,
 		valueRef,
 		displayValue,
 		subscribe,
@@ -271,6 +273,8 @@ function RafflePickRoot({ items, min = 1, max = 100, interval = 100, random = tr
 		inertia,
 		hasItems,
 		initialIndex,
+		initialValue,
+		finalValue,
 		displayValue,
 		subscribe,
 		start,
@@ -424,25 +428,26 @@ function CountdownRunning({ seconds, className, style, children }) {
 //#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)}}
+.rrp-slot{display:inline-block;position:relative;overflow:hidden;vertical-align:baseline}
+.rrp-slot__col{position:absolute;top:0;left:0;right:0;height:300%;transform:translate3d(0,-33.3333%,0);animation:rrp-slot-reel var(--rrp-tick,80ms) linear infinite;will-change:transform}
+.rrp-slot__cell{height:33.3333%;display:grid;place-items:center;padding:0;margin:0;box-sizing:border-box;text-align:center}
+.rrp-slot[data-stopped] .rrp-slot__col{animation:none;transform:translate3d(0,-33.3333%,0)}
+@keyframes rrp-slot-reel{from{transform:translate3d(0,-33.3333%,0)}to{transform:translate3d(0,-66.6666%,0)}}
 `;
-let slotStylesInjected = false;
+const SLOT_STYLES_VERSION = "4";
 const injectSlotStyles = () => {
-	if (slotStylesInjected) return;
 	if (typeof document === "undefined") return;
-	if (document.querySelector("style[data-rrp-slot-base]")) {
-		slotStylesInjected = true;
+	const existing = document.querySelector("style[data-rrp-slot-base]");
+	if (existing) {
+		if (existing.getAttribute("data-rrp-slot-base") === SLOT_STYLES_VERSION) return;
+		existing.textContent = SLOT_BASE_CSS;
+		existing.setAttribute("data-rrp-slot-base", SLOT_STYLES_VERSION);
 		return;
 	}
 	const tag = document.createElement("style");
-	tag.setAttribute("data-rrp-slot-base", "");
+	tag.setAttribute("data-rrp-slot-base", SLOT_STYLES_VERSION);
 	tag.textContent = SLOT_BASE_CSS;
 	document.head.appendChild(tag);
-	slotStylesInjected = true;
 };
 const makeRefs = () => ({
 	root: null,
@@ -455,7 +460,19 @@ const makeRefs = () => ({
 });
 function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80, staggerMs = 220, className, slotClassName, style, slotStyle, onResult }) {
 	injectSlotStyles();
-	const { phase } = useRaffleContext("RafflePick.Slots");
+	const { phase, initialValue, finalValue } = useRaffleContext("RafflePick.Slots");
+	const initialChars = useMemo(() => {
+		const seed = typeof initialValue === "string" ? initialValue : "";
+		return Array.from({ length }, (_, i) => seed[i] ?? "");
+	}, [initialValue, length]);
+	const finalChars = useMemo(() => {
+		if (typeof finalValue !== "string") return null;
+		return Array.from({ length }, (_, i) => finalValue[i] ?? "");
+	}, [finalValue, length]);
+	const finalCharsRef = useRef(finalChars);
+	useEffect(() => {
+		finalCharsRef.current = finalChars;
+	}, [finalChars]);
 	const slotsRef = useRef([]);
 	const stopTimersRef = useRef([]);
 	const finalRef = useRef([]);
@@ -513,6 +530,8 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 		for (let i = 0; i < length; i++) {
 			const id = setTimeout(() => {
 				const s = slotsRef.current[i];
+				const forced = finalCharsRef.current?.[i];
+				if (forced) writeSlot(s, s.currChar, forced, forced);
 				s.stopped = true;
 				if (s.root) s.root.setAttribute("data-stopped", "");
 				finalRef.current[i] = s.currChar;
@@ -528,17 +547,19 @@ function RafflePickSlots({ length = 3, chars = "0123456789", spinInterval = 80,
 	]);
 	useEffect(() => {
 		if (phase !== "idle") return;
-		const c = pool[0] ?? "";
+		const fallback = pool[0] ?? "";
 		for (let i = 0; i < length; i++) {
 			const s = slotsRef.current[i];
+			const c = initialChars[i] || fallback;
 			s.stopped = true;
 			writeSlot(s, c, c, c);
-			if (s.root) s.root.removeAttribute("data-stopped");
+			if (s.root) s.root.setAttribute("data-stopped", "");
 		}
 	}, [
 		phase,
 		length,
-		pool
+		pool,
+		initialChars
 	]);
 	const cls = useMemo(() => joinClassNames("rrp-slots", className), [className]);
 	const slotCls = useMemo(() => joinClassNames("rrp-slot", slotClassName), [slotClassName]);

package/dist/styles.css

@@ -4,29 +4,36 @@
 
 .rrp-slot {
   display: inline-block;
+  position: relative;
   overflow: hidden;
-  height: 1em;
-  line-height: 1em;
   vertical-align: baseline;
 }
 .rrp-slot__col {
-  display: flex;
-  flex-direction: column;
-  transform: translateY(-1em);
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 300%;
+  transform: translate3d(0, -33.3333%, 0);
   animation: rrp-slot-reel var(--rrp-tick, 80ms) linear infinite;
+  will-change: transform;
 }
 .rrp-slot__cell {
-  display: block;
-  height: 1em;
-  line-height: 1em;
+  height: 33.3333%;
+  display: grid;
+  place-items: center;
+  padding: 0;
+  margin: 0;
+  box-sizing: border-box;
+  text-align: center;
 }
 .rrp-slot[data-stopped] .rrp-slot__col {
   animation: none;
-  transform: translateY(-1em);
+  transform: translate3d(0, -33.3333%, 0);
 }
 @keyframes rrp-slot-reel {
-  from { transform: translateY(-1em); }
-  to   { transform: translateY(-2em); }
+  from { transform: translate3d(0, -33.3333%, 0); }
+  to   { transform: translate3d(0, -66.6666%, 0); }
 }
 
 /* Value animations: opt-in via <RafflePick.Value animation="..." /> */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-raffle-picker",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Headless React raffle picker for giveaways, winner draws, countdowns, and slot-machine UIs.",
   "type": "module",
   "publishConfig": {
@@ -111,5 +111,8 @@
     "typescript-eslint": "^8.58.2",
     "vite": "^8.0.8",
     "vitest": "^4.1.4"
+  },
+  "volta": {
+    "node": "22.12.0"
   }
 }