fancy-ui-svelte 0.4.1 → 0.5.0

package/README.md

@@ -119,21 +119,35 @@ Beautiful animation and UI components for **Svelte 5**.
 **Install via npm:**
 
 ```bash
-npm install fancy-ui
+npm install fancy-ui-svelte
 ```
 
 Then import any component:
 
 ```ts
-import { Marquee, BorderBeam, Confetti } from 'fancy-ui';
+import { Marquee, BorderBeam, Confetti } from 'fancy-ui-svelte';
 ```
 
-To include Tailwind classes, add this to your app's CSS:
+Add the Tailwind integration to your app's CSS (e.g. `src/app.css`):
 
 ```css
-@import "fancy-ui/tailwind.css";
+@import "tailwindcss";
+@import "fancy-ui-svelte/tailwind.css";
 ```
 
+This single import tells Tailwind v4 to scan the library's components so all utility classes are generated automatically. No manual `@source` path needed.
+
+<details>
+<summary>Alternative: manual @source (without the CSS import)</summary>
+
+```css
+@import "tailwindcss";
+@source "../node_modules/fancy-ui-svelte/dist";
+```
+
+The path is relative to your CSS file location.
+</details>
+
 **Or browse and copy a component:**
 1. Find the component you need in the [live demo](https://fancy-ui.rama.app)
 2. Copy the source from `src/lib/fancy-ui/[component-name]/`

package/dist/fancy-ui/fluid-cursor/FluidCursor.svelte

@@ -2,6 +2,9 @@
 	import { cn } from "../../utils.js";
 	import { onMount } from "svelte";
 
+	// Module-level singleton registry
+	let activeInstance: (() => void) | null = null;
+
 	interface ColorRGB {
 		r: number;
 		g: number;
@@ -27,6 +30,13 @@
 		fluidColors?: string[];
 		colorIntensity?: number;
 		class?: string;
+		autoSplat?: boolean;
+		autoSplatInterval?: number;
+		interactive?: boolean;
+		pauseWhenHidden?: boolean;
+		splatOnMount?: boolean;
+		allowMultiple?: boolean;
+		contained?: boolean;
 	}
 
 	let {
@@ -48,6 +58,13 @@
 		fluidColors,
 		colorIntensity = 0.15,
 		class: className = "",
+		autoSplat = false,
+		autoSplatInterval = 1500,
+		interactive = true,
+		pauseWhenHidden = true,
+		splatOnMount = false,
+		allowMultiple = false,
+		contained = true,
 	}: Props = $props();
 
 	function hexToRgb(hex: string): ColorRGB {
@@ -956,6 +973,28 @@
 			return Math.floor(input * pixelRatio);
 		}
 
+		let canvasRectCache: DOMRect | null = null;
+		function updateCanvasRectCache() {
+			if (contained && canvas) canvasRectCache = canvas.getBoundingClientRect();
+		}
+		if (contained) {
+			window.addEventListener("resize", updateCanvasRectCache, { passive: true });
+			window.addEventListener("scroll", updateCanvasRectCache, { passive: true });
+			updateCanvasRectCache();
+		}
+
+		function getCanvasPos(clientX: number, clientY: number): { x: number; y: number } {
+			if (contained) {
+				if (!canvasRectCache) updateCanvasRectCache();
+				const rect = canvasRectCache!;
+				return {
+					x: scaleByPixelRatio(clientX - rect.left),
+					y: scaleByPixelRatio(clientY - rect.top),
+				};
+			}
+			return { x: scaleByPixelRatio(clientX), y: scaleByPixelRatio(clientY) };
+		}
+
 		// Simulation Setup
 		updateKeywords();
 		initFramebuffers();
@@ -996,7 +1035,10 @@
 			return cachedFluidColorsScaled;
 		}
 
+		let isVisible = true;
+
 		function updateFrame() {
+			if (!isVisible) return;
 			const dt = calcDeltaTime();
 			if (resizeCanvas()) initFramebuffers();
 			updateColors(dt);
@@ -1247,6 +1289,36 @@
 			dye.swap();
 		}
 
+		function multipleSplats(steps: number) {
+			// Simulate a cursor sweep along a random arc — each step on its own frame
+			// so the velocity field has time to evolve between injections.
+			const angle = Math.random() * Math.PI * 2;
+			const cx = 0.25 + Math.random() * 0.5;
+			const cy = 0.25 + Math.random() * 0.5;
+			const arcSpan = Math.PI * (0.8 + Math.random() * 0.8);
+			let i = 0;
+
+			function step() {
+				if (i >= steps) return;
+				const t = i / Math.max(1, steps - 1);
+				const a = angle + t * arcSpan;
+				const r = 0.15 + 0.05 * Math.sin(t * Math.PI);
+				const x = cx + Math.cos(a) * r;
+				const y = cy + Math.sin(a) * r;
+				const color = generateColor();
+				splat(
+					x,
+					y,
+					-Math.sin(a) * config.SPLAT_FORCE * 0.5,
+					Math.cos(a) * config.SPLAT_FORCE * 0.5,
+					color
+				);
+				i++;
+				if (i < steps) requestAnimationFrame(step);
+			}
+			requestAnimationFrame(step);
+		}
+
 		function correctRadius(radius: number) {
 			const aspectRatio = canvas.width / canvas.height;
 			if (aspectRatio > 1) radius *= aspectRatio;
@@ -1360,37 +1432,30 @@
 		// Event Listeners
 		function handleMouseDown(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
 			updatePointerDownData(pointer, -1, posX, posY);
 			clickSplat(pointer);
 		}
 
 		function handleFirstMouseMove(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
 			const color = generateColor();
-			updateFrame();
 			updatePointerMoveData(pointer, posX, posY, color);
 			document.body.removeEventListener("mousemove", handleFirstMouseMove);
 		}
 
 		function handleMouseMove(e: MouseEvent) {
 			const pointer = pointers[0];
-			const posX = scaleByPixelRatio(e.clientX);
-			const posY = scaleByPixelRatio(e.clientY);
-			const color = pointer.color;
-			updatePointerMoveData(pointer, posX, posY, color);
+			const { x: posX, y: posY } = getCanvasPos(e.clientX, e.clientY);
+			updatePointerMoveData(pointer, posX, posY, pointer.color);
 		}
 
 		function handleFirstTouchStart(e: TouchEvent) {
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
-				updateFrame();
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerDownData(pointer, touches[i].identifier, posX, posY);
 			}
 			document.body.removeEventListener("touchstart", handleFirstTouchStart);
@@ -1400,8 +1465,7 @@
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerDownData(pointer, touches[i].identifier, posX, posY);
 			}
 		}
@@ -1410,36 +1474,108 @@
 			const touches = e.targetTouches;
 			const pointer = pointers[0];
 			for (let i = 0; i < touches.length; i++) {
-				const posX = scaleByPixelRatio(touches[i].clientX);
-				const posY = scaleByPixelRatio(touches[i].clientY);
+				const { x: posX, y: posY } = getCanvasPos(touches[i].clientX, touches[i].clientY);
 				updatePointerMoveData(pointer, posX, posY, pointer.color);
 			}
 		}
 
 		// Add event listeners
-		window.addEventListener("mousedown", handleMouseDown);
-		document.body.addEventListener("mousemove", handleFirstMouseMove);
-		window.addEventListener("mousemove", handleMouseMove);
-		document.body.addEventListener("touchstart", handleFirstTouchStart);
-		window.addEventListener("touchstart", handleTouchStart, false);
-		window.addEventListener("touchmove", handleTouchMove, false);
+		if (interactive) {
+			window.addEventListener("mousedown", handleMouseDown);
+			document.body.addEventListener("mousemove", handleFirstMouseMove);
+			window.addEventListener("mousemove", handleMouseMove);
+			document.body.addEventListener("touchstart", handleFirstTouchStart);
+			window.addEventListener("touchstart", handleTouchStart, false);
+			window.addEventListener("touchmove", handleTouchMove, false);
+		}
+
+		// Pause animation when scrolled out of view
+		let observer: IntersectionObserver | null = null;
+		if (pauseWhenHidden) {
+			observer = new IntersectionObserver(
+				([entry]) => {
+					const wasVisible = isVisible;
+					isVisible = entry.isIntersecting;
+					if (isVisible && !wasVisible) {
+						lastUpdateTime = Date.now();
+						animationFrameId = requestAnimationFrame(updateFrame);
+					}
+				},
+				{ threshold: 0 }
+			);
+			observer.observe(canvas);
+		}
 
 		// Start animation
 		updateFrame();
+		if (splatOnMount) multipleSplats(Math.floor(Math.random() * 6) + 10);
+
+		// Auto-splat timer
+		let autoSplatTimer: ReturnType<typeof setInterval> | null = null;
+		if (autoSplat) {
+			autoSplatTimer = setInterval(() => {
+				const color = generateColor();
+				splat(
+					Math.random(),
+					Math.random(),
+					(Math.random() - 0.5) * 200,
+					(Math.random() - 0.5) * 200,
+					color
+				);
+			}, autoSplatInterval);
+		}
 
 		// Cleanup
-		return () => {
+		function cleanup() {
 			cancelAnimationFrame(animationFrameId);
-			window.removeEventListener("mousedown", handleMouseDown);
-			document.body.removeEventListener("mousemove", handleFirstMouseMove);
-			window.removeEventListener("mousemove", handleMouseMove);
-			document.body.removeEventListener("touchstart", handleFirstTouchStart);
-			window.removeEventListener("touchstart", handleTouchStart);
-			window.removeEventListener("touchmove", handleTouchMove);
-		};
+			if (observer) observer.disconnect();
+			if (autoSplatTimer) clearInterval(autoSplatTimer);
+			if (interactive) {
+				window.removeEventListener("mousedown", handleMouseDown);
+				document.body.removeEventListener("mousemove", handleFirstMouseMove);
+				window.removeEventListener("mousemove", handleMouseMove);
+				document.body.removeEventListener("touchstart", handleFirstTouchStart);
+				window.removeEventListener("touchstart", handleTouchStart);
+				window.removeEventListener("touchmove", handleTouchMove);
+			}
+			if (contained) {
+				window.removeEventListener("resize", updateCanvasRectCache);
+				window.removeEventListener("scroll", updateCanvasRectCache);
+			}
+		}
+
+		if (!allowMultiple) {
+			if (activeInstance) {
+				if (import.meta.env.DEV) {
+					console.warn(
+						"[FluidCursor] Destroying previous instance. Only one instance is allowed by default. Use `allowMultiple={true}` to opt out of singleton behavior."
+					);
+				}
+				activeInstance();
+			}
+			activeInstance = cleanup;
+			return () => {
+				cleanup();
+				if (activeInstance === cleanup) {
+					activeInstance = null;
+				}
+			};
+		}
+
+		return cleanup;
 	});
 </script>
 
-<div class={cn("pointer-events-none fixed top-0 left-0 z-50 size-full", className)}>
-	<canvas bind:this={canvasRef} id="fluid" class="block h-screen w-screen"></canvas>
+<div
+	class={cn(
+		contained
+			? "pointer-events-none absolute inset-0 h-full w-full"
+			: "pointer-events-none fixed top-0 left-0 z-50 size-full",
+		className
+	)}
+>
+	<canvas
+		bind:this={canvasRef}
+		class={contained ? "block h-full w-full" : "block h-screen w-screen"}
+	></canvas>
 </div>

package/dist/fancy-ui/fluid-cursor/FluidCursor.svelte.d.ts

@@ -22,6 +22,13 @@ interface Props {
     fluidColors?: string[];
     colorIntensity?: number;
     class?: string;
+    autoSplat?: boolean;
+    autoSplatInterval?: number;
+    interactive?: boolean;
+    pauseWhenHidden?: boolean;
+    splatOnMount?: boolean;
+    allowMultiple?: boolean;
+    contained?: boolean;
 }
 declare const FluidCursor: import("svelte").Component<Props, {}, "">;
 type FluidCursor = ReturnType<typeof FluidCursor>;

package/dist/fancy-ui/fluid-cursor/FluidCursor.test.js

@@ -13,24 +13,27 @@ describe("FluidCursor", () => {
         const canvas = container.querySelector("canvas");
         expect(canvas).toBeInTheDocument();
     });
-    it('canvas has id="fluid"', () => {
-        const { container } = render(FluidCursor);
-        const canvas = container.querySelector("canvas#fluid");
-        expect(canvas).toBeInTheDocument();
-    });
     it("container has pointer-events-none class", () => {
         const { container } = render(FluidCursor);
         const div = container.firstElementChild;
         expect(div?.className).toContain("pointer-events-none");
     });
-    it("container has fixed positioning class", () => {
+    it("defaults to contained mode (absolute positioning)", () => {
         const { container } = render(FluidCursor);
         const div = container.firstElementChild;
-        expect(div?.className).toContain("fixed");
+        expect(div?.className).toContain("absolute");
+        expect(div?.className).toContain("inset-0");
     });
-    it("container has z-50 class", () => {
+    it("canvas fills container in contained mode", () => {
         const { container } = render(FluidCursor);
+        const canvas = container.querySelector("canvas");
+        expect(canvas?.className).toContain("h-full");
+        expect(canvas?.className).toContain("w-full");
+    });
+    it("uses fixed positioning when contained={false}", () => {
+        const { container } = render(FluidCursor, { props: { contained: false } });
         const div = container.firstElementChild;
+        expect(div?.className).toContain("fixed");
         expect(div?.className).toContain("z-50");
     });
     it("applies custom class names", () => {
@@ -38,6 +41,31 @@ describe("FluidCursor", () => {
         const div = container.firstElementChild;
         expect(div?.className).toContain("my-fluid");
     });
+    describe("interaction props", () => {
+        it("interactive={false} does not register mouse event listeners", () => {
+            const addSpy = vi.spyOn(window, "addEventListener");
+            render(FluidCursor, { props: { interactive: false } });
+            const mousedownCalls = addSpy.mock.calls.filter(([event]) => event === "mousedown");
+            expect(mousedownCalls).toHaveLength(0);
+            const mousemoveCalls = addSpy.mock.calls.filter(([event]) => event === "mousemove");
+            expect(mousemoveCalls).toHaveLength(0);
+            addSpy.mockRestore();
+        });
+        it("mounts without error with autoSplat={true} and splatOnMount={true}", () => {
+            const { container } = render(FluidCursor, {
+                props: { autoSplat: true, splatOnMount: true },
+            });
+            expect(container.querySelector("canvas")).toBeInTheDocument();
+        });
+        it("pauseWhenHidden={false} does not instantiate IntersectionObserver", () => {
+            const observeSpy = vi.fn();
+            const mockObserver = vi.fn(() => ({ observe: observeSpy, disconnect: vi.fn() }));
+            vi.stubGlobal("IntersectionObserver", mockObserver);
+            render(FluidCursor, { props: { pauseWhenHidden: false } });
+            expect(mockObserver).not.toHaveBeenCalled();
+            vi.unstubAllGlobals();
+        });
+    });
     describe("color props", () => {
         it("renders without error when fluidColor is provided", () => {
             const { container } = render(FluidCursor, { props: { fluidColor: "#00ffcc" } });
@@ -50,7 +78,6 @@ describe("FluidCursor", () => {
             expect(container.querySelector("canvas")).toBeInTheDocument();
         });
         it("renders without error when fluidColor and fluidColors are both provided (fluidColor takes priority)", () => {
-            // Both props accepted without throw — fluidColor priority is exercised at runtime
             const { container } = render(FluidCursor, {
                 props: { fluidColor: "#ff0000", fluidColors: ["#00ffcc", "#7700ff"] },
             });

package/dist/fancy-ui/fluid-cursor/index.d.ts

@@ -1,2 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
-export { default as FluidCursorAdvanced } from "./FluidCursorAdvanced.svelte";
+/**
+ * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
+ */
+export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";

package/dist/fancy-ui/fluid-cursor/index.js

@@ -1,2 +1,5 @@
 export { default as FluidCursor } from "./FluidCursor.svelte";
-export { default as FluidCursorAdvanced } from "./FluidCursorAdvanced.svelte";
+/**
+ * @deprecated Use `FluidCursor` instead. `FluidCursorAdvanced` has been merged into `FluidCursor`.
+ */
+export { default as FluidCursorAdvanced } from "./FluidCursor.svelte";