@flikk/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/components/effects/ParallaxSection/ParallaxSection.js

@@ -0,0 +1,71 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useRef } from 'react';
+import { useReducedMotion, useScroll, useTransform, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * ParallaxSection
+ *
+ * A scroll-driven parallax wrapper that translates its children at a configurable
+ * rate relative to normal scroll, creating depth and visual interest.
+ *
+ * Uses `transform: translate3d` for GPU-accelerated, jank-free animation.
+ *
+ * @example
+ * ```tsx
+ * <ParallaxSection speed={0.3}>
+ *   <img src="/hero-bg.jpg" alt="" className="w-full h-[600px] object-cover" />
+ * </ParallaxSection>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Opposite direction
+ * <ParallaxSection speed={-0.2} direction="horizontal">
+ *   <div className="flex gap-4">{items}</div>
+ * </ParallaxSection>
+ * ```
+ */
+const ParallaxSection = React__default.forwardRef(({ speed = 0.5, direction = 'vertical', scrollRef, className, children, style, 
+// Destructure HTML event handlers that conflict with motion's API
+onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, onAnimationStart: _onAnimationStart, ...restProps }, ref) => {
+    const shouldReduceMotion = useReducedMotion();
+    const internalRef = useRef(null);
+    // Track scroll progress of the target element through the viewport.
+    // offset: element bottom enters viewport -> element top exits viewport.
+    const { scrollYProgress } = useScroll({
+        target: internalRef,
+        container: scrollRef,
+        offset: ['start end', 'end start'],
+    });
+    // Map 0-1 scroll progress to a pixel displacement.
+    // At progress 0 (element just entering) the offset is positive (pushed down),
+    // and at progress 1 (element leaving) the offset is negative (pulled up),
+    // scaled by the speed multiplier.  This creates the classic parallax feel.
+    const range = 200 * speed;
+    const yTransform = useTransform(scrollYProgress, [0, 1], [range, -range]);
+    const xTransform = useTransform(scrollYProgress, [0, 1], [range, -range]);
+    // When reduced motion is preferred, render without any parallax.
+    if (shouldReduceMotion) {
+        return (jsx("div", { ref: (node) => {
+                internalRef.current = node;
+                if (typeof ref === 'function')
+                    ref(node);
+                else if (ref)
+                    ref.current = node;
+            }, className: cn('will-change-transform', className), style: style, ...restProps, children: children }));
+    }
+    const motionStyle = direction === 'vertical'
+        ? { y: yTransform, ...style }
+        : { x: xTransform, ...style };
+    return (jsx(motion.div, { ref: (node) => {
+            internalRef.current = node;
+            if (typeof ref === 'function')
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, className: cn('will-change-transform', className), style: motionStyle, ...restProps, children: children }));
+});
+ParallaxSection.displayName = 'ParallaxSection';
+
+export { ParallaxSection };

package/dist/components/effects/ParallaxSection/ParallaxSection.types.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+export interface ParallaxSectionProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Parallax speed multiplier. Negative = moves opposite direction. (default 0.5) */
+    speed?: number;
+    /** Direction of parallax (default 'vertical') */
+    direction?: 'vertical' | 'horizontal';
+    /** Use scroll container instead of window (ref to container) */
+    scrollRef?: RefObject<HTMLElement>;
+    className?: string;
+    children: React.ReactNode;
+}

package/dist/components/effects/ParallaxSection/index.d.ts

@@ -0,0 +1,2 @@
+export { ParallaxSection } from './ParallaxSection';
+export type { ParallaxSectionProps } from './ParallaxSection.types';

package/dist/components/effects/Particles/Particles.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+import type { ParticlesProps } from "./Particles.types";
+/**
+ * Particles creates a floating particle background effect using Three.js.
+ *
+ * Particles drift upward with slight horizontal variation and react to mouse
+ * proximity. Optional connection lines are drawn between nearby particles.
+ *
+ * The component renders as an absolutely-positioned layer, ideal for use as
+ * a section or page background.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative h-screen overflow-hidden bg-gray-950">
+ *   <Particles count={100} color="#6366f1" connectionDistance={120} />
+ *   <div className="relative z-10 p-8">
+ *     <h1 className="text-white text-4xl">Content on top</h1>
+ *   </div>
+ * </div>
+ * ```
+ */
+export declare const Particles: React.FC<ParticlesProps>;

package/dist/components/effects/Particles/Particles.js

@@ -0,0 +1,33 @@
+import { jsx } from 'react/jsx-runtime';
+import { Canvas } from '@react-three/fiber';
+import { useReducedMotion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import 'react';
+import { ParticlesScene } from './Particles.scene.js';
+
+/**
+ * Particles creates a floating particle background effect using Three.js.
+ *
+ * Particles drift upward with slight horizontal variation and react to mouse
+ * proximity. Optional connection lines are drawn between nearby particles.
+ *
+ * The component renders as an absolutely-positioned layer, ideal for use as
+ * a section or page background.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative h-screen overflow-hidden bg-gray-950">
+ *   <Particles count={100} color="#6366f1" connectionDistance={120} />
+ *   <div className="relative z-10 p-8">
+ *     <h1 className="text-white text-4xl">Content on top</h1>
+ *   </div>
+ * </div>
+ * ```
+ */
+const Particles = ({ count = 80, color = "#6366f1", size = 2, speed = 1, connectionDistance = 150, connectionColor, mouseRadius = 200, mouseForce = 0.5, opacity = 0.6, className, style, ...rest }) => {
+    var _a;
+    const shouldReduceMotion = (_a = useReducedMotion()) !== null && _a !== void 0 ? _a : false;
+    return (jsx("div", { className: cn("absolute inset-0 pointer-events-none", className), style: style, ...rest, children: jsx(Canvas, { className: "!pointer-events-auto", dpr: [1, 2], orthographic: true, camera: { zoom: 50, near: 0.1, far: 100, position: [0, 0, 10] }, gl: { antialias: false, alpha: true }, style: { position: "absolute", inset: 0, width: "100%", height: "100%" }, children: jsx(ParticlesScene, { count: count, color: color, size: size, speed: speed, connectionDistance: connectionDistance, connectionColor: connectionColor || color, mouseRadius: mouseRadius, mouseForce: mouseForce, opacity: opacity, reducedMotion: shouldReduceMotion }) }) }));
+};
+
+export { Particles };

package/dist/components/effects/Particles/Particles.scene.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { ParticlesSceneProps } from "./Particles.types";
+export declare const ParticlesScene: React.FC<ParticlesSceneProps>;

package/dist/components/effects/Particles/Particles.scene.js

@@ -0,0 +1,284 @@
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { useRef, useMemo, useEffect, useCallback } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Convert a hex colour string to a normalised THREE.Color. */
+function hexToColor(hex) {
+    return new THREE.Color(hex);
+}
+/**
+ * Seed particle data: positions scattered across an area that maps to the
+ * viewport, plus per-particle velocity and depth factor.
+ */
+function createParticleData(count, width, height) {
+    const positions = new Float32Array(count * 3);
+    const velocities = new Float32Array(count * 3);
+    const depths = new Float32Array(count); // 0 = far, 1 = near
+    const originals = new Float32Array(count * 3);
+    for (let i = 0; i < count; i++) {
+        const i3 = i * 3;
+        const x = (Math.random() - 0.5) * width;
+        const y = (Math.random() - 0.5) * height;
+        const z = 0;
+        positions[i3] = x;
+        positions[i3 + 1] = y;
+        positions[i3 + 2] = z;
+        originals[i3] = x;
+        originals[i3 + 1] = y;
+        originals[i3 + 2] = z;
+        // Random gentle velocity: slight upward float + horizontal drift
+        velocities[i3] = (Math.random() - 0.5) * 0.3; // vx
+        velocities[i3 + 1] = Math.random() * 0.2 + 0.1; // vy (upward)
+        velocities[i3 + 2] = 0; // vz
+        depths[i] = Math.random();
+    }
+    return { positions, velocities, depths, originals };
+}
+// ── Scene ────────────────────────────────────────────────────────────────────
+const ParticlesScene = ({ count, color, size, speed, connectionDistance, connectionColor, mouseRadius, mouseForce, opacity, reducedMotion, }) => {
+    const { viewport } = useThree();
+    // Refs
+    const pointsRef = useRef(null);
+    const linesRef = useRef(null);
+    const mouseNDC = useRef(new THREE.Vector2(9999, 9999));
+    // Keep latest props in a ref so useFrame reads current values
+    const propsRef = useRef({
+        speed,
+        mouseRadius,
+        mouseForce,
+        connectionDistance,
+        opacity,
+        reducedMotion,
+    });
+    propsRef.current = {
+        speed,
+        mouseRadius,
+        mouseForce,
+        connectionDistance,
+        opacity,
+        reducedMotion,
+    };
+    // Dimensions in world units
+    const worldWidth = viewport.width;
+    const worldHeight = viewport.height;
+    // ── Particle data (re-created when count or viewport changes) ────────────
+    const data = useMemo(() => createParticleData(count, worldWidth, worldHeight), [count, worldWidth, worldHeight]);
+    // ── Points geometry + material ───────────────────────────────────────────
+    const pointsGeometry = useMemo(() => {
+        const geo = new THREE.BufferGeometry();
+        geo.setAttribute("position", new THREE.BufferAttribute(data.positions, 3));
+        geo.setAttribute("depth", new THREE.BufferAttribute(data.depths, 1));
+        return geo;
+    }, [data]);
+    const pointsMaterial = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            transparent: true,
+            depthWrite: false,
+            uniforms: {
+                u_color: { value: hexToColor(color) },
+                u_size: { value: size },
+                u_opacity: { value: opacity },
+                u_pixelRatio: { value: Math.min(window.devicePixelRatio, 2) },
+            },
+            vertexShader: /* glsl */ `
+        attribute float depth;
+        uniform float u_size;
+        uniform float u_pixelRatio;
+        varying float vDepth;
+
+        void main() {
+          vDepth = depth;
+          vec4 mvPos = modelViewMatrix * vec4(position, 1.0);
+          // Larger particles appear closer (depth 1 = near, 0 = far)
+          gl_PointSize = u_size * u_pixelRatio * (0.5 + depth * 0.8);
+          gl_Position = projectionMatrix * mvPos;
+        }
+      `,
+            fragmentShader: /* glsl */ `
+        uniform vec3 u_color;
+        uniform float u_opacity;
+        varying float vDepth;
+
+        void main() {
+          // Circular point shape
+          float dist = length(gl_PointCoord - vec2(0.5));
+          if (dist > 0.5) discard;
+
+          // Soft edge falloff
+          float alpha = 1.0 - smoothstep(0.3, 0.5, dist);
+          // Depth affects brightness: closer = brighter
+          float brightness = 0.4 + vDepth * 0.6;
+          gl_FragColor = vec4(u_color * brightness, alpha * u_opacity * (0.3 + vDepth * 0.7));
+        }
+      `,
+        });
+    }, [color, size, opacity]);
+    // Update material uniforms when props change
+    useEffect(() => {
+        if (pointsMaterial) {
+            pointsMaterial.uniforms.u_color.value = hexToColor(color);
+            pointsMaterial.uniforms.u_size.value = size;
+            pointsMaterial.uniforms.u_opacity.value = opacity;
+        }
+    }, [color, size, opacity, pointsMaterial]);
+    // ── Connection lines geometry + material ─────────────────────────────────
+    const maxLines = count * 6; // upper bound on line segments
+    const linesGeometry = useMemo(() => {
+        const geo = new THREE.BufferGeometry();
+        const linePositions = new Float32Array(maxLines * 6); // 2 verts * 3 coords per segment
+        const lineAlphas = new Float32Array(maxLines * 2); // alpha per vertex
+        geo.setAttribute("position", new THREE.BufferAttribute(linePositions, 3));
+        geo.setAttribute("alpha", new THREE.BufferAttribute(lineAlphas, 1));
+        geo.setDrawRange(0, 0);
+        return geo;
+    }, [maxLines]);
+    const linesMaterial = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            transparent: true,
+            depthWrite: false,
+            uniforms: {
+                u_color: { value: hexToColor(connectionColor || color) },
+                u_opacity: { value: opacity },
+            },
+            vertexShader: /* glsl */ `
+        attribute float alpha;
+        varying float vAlpha;
+
+        void main() {
+          vAlpha = alpha;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+      `,
+            fragmentShader: /* glsl */ `
+        uniform vec3 u_color;
+        uniform float u_opacity;
+        varying float vAlpha;
+
+        void main() {
+          gl_FragColor = vec4(u_color, vAlpha * u_opacity * 0.35);
+        }
+      `,
+        });
+    }, [color, connectionColor, opacity]);
+    // Update line material when props change
+    useEffect(() => {
+        if (linesMaterial) {
+            linesMaterial.uniforms.u_color.value = hexToColor(connectionColor || color);
+            linesMaterial.uniforms.u_opacity.value = opacity;
+        }
+    }, [color, connectionColor, opacity, linesMaterial]);
+    // ── Mouse tracking ───────────────────────────────────────────────────────
+    const handlePointerMove = useCallback((event) => {
+        mouseNDC.current.set(event.point.x, event.point.y);
+    }, []);
+    const handlePointerLeave = useCallback(() => {
+        // Move mouse far away so it has no effect
+        mouseNDC.current.set(9999, 9999);
+    }, []);
+    // ── Cleanup on unmount ───────────────────────────────────────────────────
+    useEffect(() => {
+        return () => {
+            pointsGeometry.dispose();
+            pointsMaterial.dispose();
+            linesGeometry.dispose();
+            linesMaterial.dispose();
+        };
+    }, [pointsGeometry, pointsMaterial, linesGeometry, linesMaterial]);
+    // ── Animation loop ───────────────────────────────────────────────────────
+    useFrame((_, delta) => {
+        const { speed: spd, mouseRadius: mRadius, mouseForce: mForce, connectionDistance: connDist, opacity: opac, reducedMotion: reduced, } = propsRef.current;
+        if (reduced)
+            return; // Respect reduced motion preference
+        const clampedDelta = Math.min(delta, 0.05); // cap to prevent large jumps
+        const dt = clampedDelta * spd;
+        const posAttr = pointsGeometry.getAttribute("position");
+        const posArr = posAttr.array;
+        const halfW = worldWidth / 2;
+        const halfH = worldHeight / 2;
+        const mx = mouseNDC.current.x;
+        const my = mouseNDC.current.y;
+        // Convert connectionDistance from screen-pixels to world units.
+        // viewport.width corresponds to the canvas pixel width, so we scale.
+        const connDistWorld = (connDist / (viewport.width * 50)) * worldWidth;
+        const mouseRadiusWorld = (mRadius / (viewport.width * 50)) * worldWidth;
+        // ── Update particle positions ────────────────────────────────────────
+        for (let i = 0; i < count; i++) {
+            const i3 = i * 3;
+            // Apply velocity (floating upward + drift)
+            posArr[i3] += data.velocities[i3] * dt;
+            posArr[i3 + 1] += data.velocities[i3 + 1] * dt;
+            // Mouse repulsion
+            if (mRadius > 0) {
+                const dx = posArr[i3] - mx;
+                const dy = posArr[i3 + 1] - my;
+                const distSq = dx * dx + dy * dy;
+                const mRadSq = mouseRadiusWorld * mouseRadiusWorld;
+                if (distSq < mRadSq && distSq > 0.0001) {
+                    const dist = Math.sqrt(distSq);
+                    const force = ((mouseRadiusWorld - dist) / mouseRadiusWorld) * mForce * dt;
+                    posArr[i3] += (dx / dist) * force;
+                    posArr[i3 + 1] += (dy / dist) * force;
+                }
+            }
+            // Wrap around edges
+            if (posArr[i3] > halfW)
+                posArr[i3] = -halfW;
+            if (posArr[i3] < -halfW)
+                posArr[i3] = halfW;
+            if (posArr[i3 + 1] > halfH) {
+                posArr[i3 + 1] = -halfH;
+                // Re-randomize x when wrapping vertically for natural look
+                posArr[i3] = (Math.random() - 0.5) * worldWidth;
+            }
+            if (posArr[i3 + 1] < -halfH)
+                posArr[i3 + 1] = halfH;
+        }
+        posAttr.needsUpdate = true;
+        // ── Update connection lines ──────────────────────────────────────────
+        if (connDist > 0 && linesGeometry) {
+            const linePosAttr = linesGeometry.getAttribute("position");
+            const lineAlphaAttr = linesGeometry.getAttribute("alpha");
+            const linePosArr = linePosAttr.array;
+            const lineAlphaArr = lineAlphaAttr.array;
+            let lineIdx = 0;
+            const connDistSq = connDistWorld * connDistWorld;
+            for (let i = 0; i < count && lineIdx < maxLines; i++) {
+                const i3 = i * 3;
+                for (let j = i + 1; j < count && lineIdx < maxLines; j++) {
+                    const j3 = j * 3;
+                    const dx = posArr[i3] - posArr[j3];
+                    const dy = posArr[i3 + 1] - posArr[j3 + 1];
+                    const distSq = dx * dx + dy * dy;
+                    if (distSq < connDistSq) {
+                        const lineBase = lineIdx * 6;
+                        const alphaBase = lineIdx * 2;
+                        linePosArr[lineBase] = posArr[i3];
+                        linePosArr[lineBase + 1] = posArr[i3 + 1];
+                        linePosArr[lineBase + 2] = 0;
+                        linePosArr[lineBase + 3] = posArr[j3];
+                        linePosArr[lineBase + 4] = posArr[j3 + 1];
+                        linePosArr[lineBase + 5] = 0;
+                        const alpha = 1.0 - Math.sqrt(distSq) / connDistWorld;
+                        lineAlphaArr[alphaBase] = alpha;
+                        lineAlphaArr[alphaBase + 1] = alpha;
+                        lineIdx++;
+                    }
+                }
+            }
+            linesGeometry.setDrawRange(0, lineIdx * 2);
+            linePosAttr.needsUpdate = true;
+            lineAlphaAttr.needsUpdate = true;
+            if (linesMaterial) {
+                linesMaterial.uniforms.u_opacity.value = opac;
+            }
+        }
+        else if (linesGeometry) {
+            linesGeometry.setDrawRange(0, 0);
+        }
+    });
+    return (jsxs(Fragment, { children: [jsxs("mesh", { onPointerMove: handlePointerMove, onPointerLeave: handlePointerLeave, children: [jsx("planeGeometry", { args: [worldWidth * 2, worldHeight * 2] }), jsx("meshBasicMaterial", { transparent: true, opacity: 0, depthWrite: false })] }), jsx("points", { ref: pointsRef, geometry: pointsGeometry, material: pointsMaterial }), connectionDistance > 0 && (jsx("lineSegments", { ref: linesRef, geometry: linesGeometry, material: linesMaterial }))] }));
+};
+
+export { ParticlesScene };

package/dist/components/effects/Particles/Particles.types.d.ts

@@ -0,0 +1,65 @@
+import React from "react";
+export interface ParticlesProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+    /**
+     * Number of particles to render.
+     * @default 80
+     */
+    count?: number;
+    /**
+     * Particle colour as a CSS hex string.
+     * @default '#6366f1'
+     */
+    color?: string;
+    /**
+     * Base particle size in pixels.
+     * @default 2
+     */
+    size?: number;
+    /**
+     * Animation speed multiplier (1 = normal).
+     * @default 1
+     */
+    speed?: number;
+    /**
+     * Maximum pixel distance between particles to draw a connection line.
+     * Set to 0 to disable connection lines entirely.
+     * @default 150
+     */
+    connectionDistance?: number;
+    /**
+     * Colour of the connection lines between particles.
+     * Defaults to the same value as `color` when omitted.
+     */
+    connectionColor?: string;
+    /**
+     * Pixel radius within which the mouse affects particles.
+     * Set to 0 to disable mouse interaction.
+     * @default 200
+     */
+    mouseRadius?: number;
+    /**
+     * Strength of the push force applied by the mouse cursor.
+     * @default 0.5
+     */
+    mouseForce?: number;
+    /**
+     * Overall opacity of the particle layer (0 to 1).
+     * @default 0.6
+     */
+    opacity?: number;
+}
+/**
+ * Internal props forwarded to the Three.js scene component.
+ */
+export interface ParticlesSceneProps {
+    count: number;
+    color: string;
+    size: number;
+    speed: number;
+    connectionDistance: number;
+    connectionColor: string;
+    mouseRadius: number;
+    mouseForce: number;
+    opacity: number;
+    reducedMotion: boolean;
+}

package/dist/components/effects/Particles/index.d.ts

@@ -0,0 +1,2 @@
+export { Particles } from "./Particles";
+export type { ParticlesProps } from "./Particles.types";

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { ProgressiveBlurProps } from "./ProgressiveBlur.types";
+export declare const ProgressiveBlur: React.ForwardRefExoticComponent<ProgressiveBlurProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.js

@@ -0,0 +1,75 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { forwardRef, useMemo } from 'react';
+import { cn } from '../../../utils/cn.js';
+import { progressiveBlurTheme } from './ProgressiveBlur.theme.js';
+
+const DEFAULT_LAYERS = 8;
+const DEFAULT_MAX_BLUR = 64;
+const DEFAULT_SIZE = "30%";
+/**
+ * Generate exponentially distributed blur levels (powers of 2).
+ * e.g. for 8 layers with max 64: [0.5, 1, 2, 4, 8, 16, 32, 64]
+ */
+function generateBlurLevels(layers, maxBlur) {
+    return Array.from({ length: layers }, (_, i) => maxBlur * Math.pow(2, i - (layers - 1)));
+}
+const GRADIENT_DIRECTIONS = {
+    top: "to top",
+    bottom: "to bottom",
+    left: "to left",
+    right: "to right",
+};
+/**
+ * Renders a single blur instance for one position.
+ */
+const BlurInstance = forwardRef(({ position, blurLevels, size, theme, className, style, ...rest }, ref) => {
+    const isVertical = position === "top" || position === "bottom";
+    const direction = GRADIENT_DIRECTIONS[position];
+    const n = blurLevels.length;
+    const containerStyle = {
+        ...(isVertical ? { height: size } : { width: size }),
+        ...style,
+    };
+    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, theme.positions[position], className), style: containerStyle, ...rest, children: blurLevels.map((blur, i) => {
+            // MagicUI mask formula: each layer has a 1-step fade-in, 1-step solid,
+            // and 1-step fade-out. Adjacent layers overlap by 2 steps, creating
+            // smooth transitions. Values beyond 100% are clamped by the browser.
+            const step = 100 / n;
+            const gradient = `linear-gradient(${direction}, transparent ${i * step}%, black ${(i + 1) * step}%, black ${(i + 2) * step}%, transparent ${(i + 3) * step}%)`;
+            const layerStyle = {
+                maskImage: gradient,
+                WebkitMaskImage: gradient,
+                backdropFilter: `blur(${blur}px)`,
+                WebkitBackdropFilter: `blur(${blur}px)`,
+                zIndex: i + 1,
+            };
+            return (jsx("div", { className: theme.layerStyle, style: layerStyle }, i));
+        }) }));
+});
+BlurInstance.displayName = "BlurInstance";
+const ProgressiveBlur = forwardRef(({ position = "bottom", blurLevels: blurLevelsProp, layers = DEFAULT_LAYERS, blurIntensity = DEFAULT_MAX_BLUR, size = DEFAULT_SIZE, className, theme: themeOverrides, ...rest }, ref) => {
+    const theme = useMemo(() => {
+        var _a, _b;
+        return ({
+            baseStyle: (_a = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.baseStyle) !== null && _a !== void 0 ? _a : progressiveBlurTheme.baseStyle,
+            positions: {
+                ...progressiveBlurTheme.positions,
+                ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.positions,
+            },
+            layerStyle: (_b = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.layerStyle) !== null && _b !== void 0 ? _b : progressiveBlurTheme.layerStyle,
+        });
+    }, [themeOverrides]);
+    const blurLevels = useMemo(() => blurLevelsProp !== null && blurLevelsProp !== void 0 ? blurLevelsProp : generateBlurLevels(layers, blurIntensity), [blurLevelsProp, layers, blurIntensity]);
+    const positions = Array.isArray(position)
+        ? position
+        : [position];
+    // Single position — render directly, forward ref and remaining props
+    if (positions.length === 1) {
+        return (jsx(BlurInstance, { ref: ref, position: positions[0], blurLevels: blurLevels, size: size, theme: theme, className: className, ...rest }));
+    }
+    // Multiple positions — render one BlurInstance per position
+    return (jsx(Fragment, { children: positions.map((pos) => (jsx(BlurInstance, { position: pos, blurLevels: blurLevels, size: size, theme: theme, className: className, ...rest }, pos))) }));
+});
+ProgressiveBlur.displayName = "ProgressiveBlur";
+
+export { ProgressiveBlur };

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.theme.d.ts

@@ -0,0 +1,7 @@
+import type { ProgressiveBlurPosition } from "./ProgressiveBlur.types";
+export interface ProgressiveBlurTheme {
+    baseStyle: string;
+    positions: Record<ProgressiveBlurPosition, string>;
+    layerStyle: string;
+}
+export declare const progressiveBlurTheme: ProgressiveBlurTheme;

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.theme.js

@@ -0,0 +1,12 @@
+const progressiveBlurTheme = {
+    baseStyle: "absolute pointer-events-none z-10",
+    positions: {
+        top: "top-0 left-0 right-0",
+        bottom: "bottom-0 left-0 right-0",
+        left: "left-0 top-0 bottom-0",
+        right: "right-0 top-0 bottom-0",
+    },
+    layerStyle: "absolute inset-0",
+};
+
+export { progressiveBlurTheme };

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.types.d.ts

@@ -0,0 +1,47 @@
+import React from "react";
+export type ProgressiveBlurPosition = "top" | "bottom" | "left" | "right";
+export interface ProgressiveBlurProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Position(s) where the blur effect should be applied.
+     * Can be a single position or array of positions.
+     * @default "bottom"
+     */
+    position?: ProgressiveBlurPosition | ProgressiveBlurPosition[];
+    /**
+     * Custom blur levels array (in pixels) for fine-grained control.
+     * If provided, overrides `layers` and `blurIntensity`.
+     * @example [0.5, 1, 2, 4, 8, 16, 32, 64]
+     */
+    blurLevels?: number[];
+    /**
+     * Number of blur layers to generate.
+     * More layers = smoother gradient, but more DOM nodes.
+     * Ignored if `blurLevels` is provided.
+     * @default 8
+     */
+    layers?: number;
+    /**
+     * Maximum blur value in pixels for auto-generated levels.
+     * Ignored if `blurLevels` is provided.
+     * @default 64
+     */
+    blurIntensity?: number;
+    /**
+     * Size of the blur region.
+     * Height for top/bottom positions, width for left/right positions.
+     * @default "30%"
+     */
+    size?: string;
+    /** Custom className for styling overrides */
+    className?: string;
+    /** Theme overrides */
+    theme?: ProgressiveBlurThemeOverrides;
+}
+export interface ProgressiveBlurThemeOverrides {
+    /** Base styles for each blur instance container */
+    baseStyle?: string;
+    /** Position-specific styles */
+    positions?: Partial<Record<ProgressiveBlurPosition, string>>;
+    /** Styles for each individual blur layer div */
+    layerStyle?: string;
+}

package/dist/components/effects/ProgressiveBlur/index.d.ts

@@ -0,0 +1,2 @@
+export { ProgressiveBlur } from "./ProgressiveBlur";
+export type { ProgressiveBlurProps, ProgressiveBlurPosition, ProgressiveBlurThemeOverrides, } from "./ProgressiveBlur.types";