3d-effect-cinema 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # 🎬 3D Effect Cinema
 
-> High-performance, customizable 3D Cinema Loader & Interactive WebGL Background Experience for React and Next.js powered by `@react-three/fiber` & `three`.
+> High-performance, highly customizable 3D Cinema WebGL Experience, HOC & Dynamic Background for React and Next.js powered by `@react-three/fiber` & `three`.
 
 [![npm version](https://img.shields.io/npm/v/3d-effect-cinema.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/3d-effect-cinema)
 [![license](https://img.shields.io/npm/l/3d-effect-cinema.svg?style=flat-square)](https://github.com/esteban284/3d-effect-cinema)
@@ -9,34 +9,29 @@
 
 ---
 
-## 🚀 Live Demo & Preview
+## 🚀 Live Demo
 
 👉 **[Ver Demo en Vivo (Vercel)](https://cinema-animation-sample.vercel.app)**
 
-```
-+-------------------------------------------------------------------------------+
-|  🌟 CINEMULTIPLEX 3D - Fire Sparks & Dynamic WebGL Hero Background            |
-|  [ Gold ] [ Neon ] [ Emerald ] [ Crimson ] [ Obsidian ] [ Glass ]             |
-+-------------------------------------------------------------------------------+
-```
-
 ---
 
 ## ✨ Features
 
-- 💥 **Interactive Fire Sparks**: Click or touch anywhere on screen to trigger explosive 3D fire embers and local light flashes.
-- 🖼️ **Dynamic Hero Background (`<CinemaBackground />`)**: Embed the 3D WebGL background inside any container (div, hero section, card) with auto-resizing.
-- 🌟 **Cinematic 3D Typography**: Animated 3D extruded text with spring physics.
+- 🪄 **Higher-Order Component (`withCinema3D`)**: Easily wrap any React component with a dynamic 3D WebGL background.
+- 🖼️ **Dynamic Container Background (`<CinemaBackground />`)**: Fits inside any parent container (`div`, `header`, `section`, `card`) with responsive auto-resizing.
+- ✍️ **Live 3D Title Control**: Dynamic text input that updates the 3D typography in real-time.
+- 🎛️ **Interactive FX Toggles Bar**: Toggle buttons to control 3D Fire Sparks, Shockwave rings, Electric Plasma, and Ambient Embers.
+- 💥 **Multiple Interactive 3D Effects**:
+  - 🔥 **`ClickFireSparks`**: Explosive fire ember burst & local point light flash on click.
+  - 🌊 **`ClickShockwave`**: Expanding 3D energy ring wave on click.
+  - ⚡ **`ElectricPlasma`**: Interactive electric plasma tendrils reacting to pointer movement.
+  - ✨ **`SceneParticles`**: Thermal rising ambient embers.
 - 🎨 **6 Material Themes**: `emerald` (Matrix Luxe), `crimson` (Ruby Fire), `gold`, `neon`, `obsidian`, `glass`.
-- 🎥 **Cinematic Camera Rig**: Camera dolly zoom, subtle mouse parallax, and breathing float movement.
-- ⚡ **Next.js & React 19 Ready**: Pre-configured with `'use client'` directives for seamless App Router integration.
 
 ---
 
 ## 📦 Installation
 
-Install the package and its peer dependencies in your React / Next.js project:
-
 ```bash
 npm install 3d-effect-cinema three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing
 ```
@@ -45,102 +40,101 @@ npm install 3d-effect-cinema three @react-three/fiber @react-three/drei @react-t
 
 ## 🚀 Usage Examples
 
-### 1. Dynamic Hero Section Background (`<CinemaBackground />`)
+### 1. Using the HOC (`withCinema3D`)
 
-Embed the interactive 3D WebGL experience inside any section of your website:
+Wrap any existing React component with the 3D WebGL background:
 
 ```tsx
 "use client";
 
-import { CinemaBackground } from "3d-effect-cinema";
+import { withCinema3D } from "3d-effect-cinema";
 
-export default function HeroSection() {
+function LandingHero() {
   return (
-    <div className="relative w-full h-[600px]">
-      <CinemaBackground
-        text="UNITED OF WEB"
-        theme="emerald"
-        interactiveSparks={true}
-      >
-        {/* Your HTML/React overlays on top of the 3D scene */}
-        <div className="text-center text-white pointer-events-auto">
-          <h2 className="text-4xl font-bold tracking-widest uppercase">
-            Search Optimization Engine
-          </h2>
-          <button className="mt-6 px-8 py-3 bg-emerald-500 hover:bg-emerald-400 text-black font-bold uppercase rounded-md transition-all">
-            Explore Services
-          </button>
-        </div>
-      </CinemaBackground>
+    <div className="text-center text-white py-24">
+      <h1 className="text-5xl font-bold uppercase tracking-widest">
+        Enterprise Solutions
+      </h1>
+      <p className="mt-4 text-white/70 max-w-xl mx-auto">
+        Build high-performance 3D web experiences effortlessly.
+      </p>
     </div>
   );
 }
+
+// Export wrapped with 3D Cinema background
+export default withCinema3D(LandingHero, {
+  text: "UNITED OF WEB",
+  theme: "emerald",
+  interactiveSparks: true,
+  interactiveShockwave: true,
+  interactivePlasma: true,
+});
 ```
 
 ---
 
-### 2. Full Screen Cinema Experience (`<CinemaLoader />`)
+### 2. Using the Component (`<CinemaBackground />`)
+
+Embed directly inside any container in your layout:
 
 ```tsx
 "use client";
 
-import { useState } from "react";
-import { CinemaLoader, CinemaHome } from "3d-effect-cinema";
-
-export default function App() {
-  const [loaded, setLoaded] = useState(false);
-
-  if (!loaded) {
-    return (
-      <CinemaLoader
-        cinemaName="NOVA CINEMA"
-        defaultTheme="emerald"
-        onEnterCinema={() => setLoaded(true)}
-      />
-    );
-  }
+import { CinemaBackground } from "3d-effect-cinema";
 
-  return <CinemaHome cinemaName="NOVA CINEMA" webTheme="neon" />;
+export default function CustomCard() {
+  return (
+    <div className="w-full h-[500px] rounded-2xl overflow-hidden shadow-2xl">
+      <CinemaBackground
+        text="CREATIVE"
+        theme="crimson"
+        interactiveSparks={true}
+        interactivePlasma={true}
+      >
+        <button className="px-8 py-3 bg-red-600 hover:bg-red-500 text-white font-bold uppercase rounded-full">
+          Get Started
+        </button>
+      </CinemaBackground>
+    </div>
+  );
 }
 ```
 
 ---
 
-## 🎨 Material Themes
-
-| Theme | Description | Visual Style |
-| :--- | :--- | :--- |
-| `emerald` | Deep Matrix green green metallic glow with emerald embers | 💚 Matrix Luxe |
-| `crimson` | Fiery ruby red emissive metal with flame embers | ❤️ Ruby Fire |
-| `gold` | High-metallic polished gold with warm ambient glow | 🌟 Luxe Gold |
-| `neon` | Cyberpunk cyan with vibrant emissive bloom | ⚡ Cyberpunk Neon |
-| `obsidian` | Deep glossy purple mineral with high environment reflection | 💜 Obsidian Dark |
-| `glass` | Refractive glass material with chromatic dispersion | 💎 Refractive Glass |
-
----
+### 3. Full Interactive Playground & Loader (`<CinemaLoader />`)
 
-## 🛠️ API Reference
+```tsx
+"use client";
 
-### `<CinemaBackground />`
+import { CinemaLoader } from "3d-effect-cinema";
 
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `text` | `string` | `"CINEMA"` | 3D Text rendered in space |
-| `theme` | `'emerald' \| 'crimson' \| 'gold' \| 'neon' \| 'obsidian' \| 'glass'` | `'emerald'` | Material & light theme |
-| `customBackground` | `string` | `undefined` | Custom CSS gradient or color (e.g., `"radial-gradient(...)"`) |
-| `interactiveSparks` | `boolean` | `true` | Enables/disables fire sparks on mouse click |
-| `showParticles` | `boolean` | `true` | Enables/disables ambient floating embers |
+export default function InteractiveDemo() {
+  return (
+    <CinemaLoader
+      cinemaName="NOVA CINEMA"
+      defaultTheme="emerald"
+    />
+  );
+}
+```
 
 ---
 
-### `<CinemaLoader />`
+## 🛠️ Props Reference
+
+### `<CinemaBackground />` & `withCinema3D(Component, options)`
 
-| Prop | Type | Default | Description |
+| Prop / Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `cinemaName` | `string` | `"CINEMULTIPLEX"` | Brand text displayed in 3D typography and UI |
-| `defaultTheme` | `MaterialTheme` | `'gold'` | Initial material theme |
-| `customBackground` | `string` | `undefined` | Override CSS background gradient |
-| `onEnterCinema` | `() => void` | **Required** | Callback triggered when user clicks Enter |
+| `text` | `string` | `"CINEMA"` | 3D Text rendered in world space |
+| `theme` | `'emerald' \| 'crimson' \| 'gold' \| 'neon' \| 'obsidian' \| 'glass'` | `'emerald'` | Material & lighting preset |
+| `customBackground` | `string` | `undefined` | Custom CSS gradient or color |
+| `interactiveSparks` | `boolean` | `true` | Enable/disable fire sparks on click |
+| `interactiveShockwave` | `boolean` | `true` | Enable/disable shockwave rings on click |
+| `interactivePlasma` | `boolean` | `true` | Enable/disable electric plasma arcs |
+| `showParticles` | `boolean` | `true` | Enable/disable ambient floating embers |
 
 ---
 

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import react__default from 'react';
 
 type MaterialTheme = "gold" | "neon" | "emerald" | "crimson" | "obsidian" | "glass";
 interface AnimatedLetterProps {
@@ -12,31 +13,77 @@ interface AnimatedLetterProps {
 }
 declare function AnimatedLetter({ char, index, totalLetters, position, phase, theme, fontUrl, }: AnimatedLetterProps): react.JSX.Element | null;
 
-interface CameraRigProps {
-    phase: "loading" | "entering" | "idle" | "exiting";
+interface CinemaBackgroundProps {
+    /** 3D Text rendered in world space */
+    text?: string;
+    /** Active material & lighting theme */
+    theme?: MaterialTheme;
+    /** Custom CSS gradient or solid color */
+    customBackground?: string;
+    /** Enable/disable 3D fire sparks on click */
+    interactiveSparks?: boolean;
+    /** Enable/disable 3D shockwave rings on click */
+    interactiveShockwave?: boolean;
+    /** Enable/disable electric plasma arcs */
+    interactivePlasma?: boolean;
+    /** Enable/disable ambient floating particle embers */
+    showParticles?: boolean;
+    /** Enable bloom glow effect */
+    enableBloom?: boolean;
+    /** Optional container CSS class name */
+    className?: string;
+    /** Optional inline container styles */
+    style?: React.CSSProperties;
+    /** Children React nodes rendered on top of the 3D canvas */
+    children?: React.ReactNode;
 }
-declare function CameraRig({ phase }: CameraRigProps): null;
+/**
+ * Highly customizable 3D Cinema WebGL Background Component.
+ * Fits dynamically into any HTML parent container (div, header, section, card).
+ */
+declare function CinemaBackground({ text, theme, customBackground, interactiveSparks, interactiveShockwave, interactivePlasma, showParticles, enableBloom, className, style, children, }: CinemaBackgroundProps): react.JSX.Element;
+
+interface WithCinema3DOptions extends Omit<CinemaBackgroundProps, "children"> {
+}
+/**
+ * Higher-Order Component (HOC) that wraps any React component with the 3D WebGL Cinema background.
+ *
+ * @example
+ * const HeroWith3D = withCinema3D(MyHeroComponent, {
+ *   text: "UNITED OF WEB",
+ *   theme: "emerald",
+ *   interactiveSparks: true,
+ *   interactiveShockwave: true,
+ * });
+ */
+declare function withCinema3D<P extends object>(WrappedComponent: react__default.ComponentType<P>, hocOptions?: WithCinema3DOptions): {
+    (props: P): react__default.JSX.Element;
+    displayName: string;
+};
 
 interface CinemaLoaderProps {
     cinemaName?: string;
     defaultTheme?: MaterialTheme;
     customBackground?: string;
-    onEnterCinema: () => void;
+    onEnterCinema?: () => void;
 }
 declare function CinemaLoader({ cinemaName, defaultTheme, customBackground, onEnterCinema, }: CinemaLoaderProps): react.JSX.Element;
 
-declare function ClickFireSparks({ theme }: {
+declare function ClickFireSparks({ theme, enabled, }: {
     theme?: MaterialTheme;
+    enabled?: boolean;
 }): react.JSX.Element;
 
-interface LoaderOverlayProps {
-    phase: "loading" | "entering" | "idle" | "exiting";
-    cinemaName: string;
-    theme: MaterialTheme;
-    onEnter: () => void;
-    onThemeChange: (theme: MaterialTheme) => void;
+declare function ClickShockwave({ theme, enabled, }: {
+    theme?: MaterialTheme;
+    enabled?: boolean;
+}): react.JSX.Element | null;
+
+interface ElectricPlasmaProps {
+    theme?: MaterialTheme;
+    enabled?: boolean;
 }
-declare function LoaderOverlay({ phase, cinemaName, theme, onEnter, onThemeChange, }: LoaderOverlayProps): react.JSX.Element;
+declare function ElectricPlasma({ theme, enabled, }: ElectricPlasmaProps): react.JSX.Element | null;
 
 interface SceneParticlesProps {
     theme: MaterialTheme;
@@ -44,25 +91,31 @@ interface SceneParticlesProps {
 }
 declare function SceneParticles({ theme, visible }: SceneParticlesProps): react.JSX.Element | null;
 
-interface CinemaBackgroundProps {
-    text?: string;
-    theme?: MaterialTheme;
-    customBackground?: string;
-    interactiveSparks?: boolean;
-    showParticles?: boolean;
-    className?: string;
-    style?: React.CSSProperties;
-    children?: React.ReactNode;
+interface CameraRigProps {
+    phase: "loading" | "entering" | "idle" | "exiting";
 }
-/**
- * Reusable 3D Cinema Background Component.
- * Fits dynamically inside any parent container (div, header, section).
- */
-declare function CinemaBackground({ text, theme, customBackground, interactiveSparks, showParticles, className, style, children, }: CinemaBackgroundProps): react.JSX.Element;
+declare function CameraRig({ phase }: CameraRigProps): null;
+
+interface EffectState {
+    sparks: boolean;
+    shockwave: boolean;
+    plasma: boolean;
+    embers: boolean;
+}
+interface LoaderOverlayProps {
+    phase: "loading" | "entering" | "idle" | "exiting";
+    cinemaName: string;
+    theme: MaterialTheme;
+    effects: EffectState;
+    onTitleChange: (newTitle: string) => void;
+    onThemeChange: (theme: MaterialTheme) => void;
+    onToggleEffect: (effectName: keyof EffectState) => void;
+}
+declare function LoaderOverlay({ phase, cinemaName, theme, effects, onTitleChange, onThemeChange, onToggleEffect, }: LoaderOverlayProps): react.JSX.Element;
 
 declare function CinemaHome({ cinemaName, webTheme }: {
     cinemaName?: string;
     webTheme?: string;
 }): react.JSX.Element;
 
-export { AnimatedLetter, CameraRig, CinemaBackground, type CinemaBackgroundProps, CinemaHome, CinemaLoader, ClickFireSparks, LoaderOverlay, type MaterialTheme, SceneParticles };
+export { AnimatedLetter, CameraRig, CinemaBackground, type CinemaBackgroundProps, CinemaHome, CinemaLoader, ClickFireSparks, ClickShockwave, type EffectState, ElectricPlasma, LoaderOverlay, type MaterialTheme, SceneParticles, type WithCinema3DOptions, withCinema3D };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import react__default from 'react';
 
 type MaterialTheme = "gold" | "neon" | "emerald" | "crimson" | "obsidian" | "glass";
 interface AnimatedLetterProps {
@@ -12,31 +13,77 @@ interface AnimatedLetterProps {
 }
 declare function AnimatedLetter({ char, index, totalLetters, position, phase, theme, fontUrl, }: AnimatedLetterProps): react.JSX.Element | null;
 
-interface CameraRigProps {
-    phase: "loading" | "entering" | "idle" | "exiting";
+interface CinemaBackgroundProps {
+    /** 3D Text rendered in world space */
+    text?: string;
+    /** Active material & lighting theme */
+    theme?: MaterialTheme;
+    /** Custom CSS gradient or solid color */
+    customBackground?: string;
+    /** Enable/disable 3D fire sparks on click */
+    interactiveSparks?: boolean;
+    /** Enable/disable 3D shockwave rings on click */
+    interactiveShockwave?: boolean;
+    /** Enable/disable electric plasma arcs */
+    interactivePlasma?: boolean;
+    /** Enable/disable ambient floating particle embers */
+    showParticles?: boolean;
+    /** Enable bloom glow effect */
+    enableBloom?: boolean;
+    /** Optional container CSS class name */
+    className?: string;
+    /** Optional inline container styles */
+    style?: React.CSSProperties;
+    /** Children React nodes rendered on top of the 3D canvas */
+    children?: React.ReactNode;
 }
-declare function CameraRig({ phase }: CameraRigProps): null;
+/**
+ * Highly customizable 3D Cinema WebGL Background Component.
+ * Fits dynamically into any HTML parent container (div, header, section, card).
+ */
+declare function CinemaBackground({ text, theme, customBackground, interactiveSparks, interactiveShockwave, interactivePlasma, showParticles, enableBloom, className, style, children, }: CinemaBackgroundProps): react.JSX.Element;
+
+interface WithCinema3DOptions extends Omit<CinemaBackgroundProps, "children"> {
+}
+/**
+ * Higher-Order Component (HOC) that wraps any React component with the 3D WebGL Cinema background.
+ *
+ * @example
+ * const HeroWith3D = withCinema3D(MyHeroComponent, {
+ *   text: "UNITED OF WEB",
+ *   theme: "emerald",
+ *   interactiveSparks: true,
+ *   interactiveShockwave: true,
+ * });
+ */
+declare function withCinema3D<P extends object>(WrappedComponent: react__default.ComponentType<P>, hocOptions?: WithCinema3DOptions): {
+    (props: P): react__default.JSX.Element;
+    displayName: string;
+};
 
 interface CinemaLoaderProps {
     cinemaName?: string;
     defaultTheme?: MaterialTheme;
     customBackground?: string;
-    onEnterCinema: () => void;
+    onEnterCinema?: () => void;
 }
 declare function CinemaLoader({ cinemaName, defaultTheme, customBackground, onEnterCinema, }: CinemaLoaderProps): react.JSX.Element;
 
-declare function ClickFireSparks({ theme }: {
+declare function ClickFireSparks({ theme, enabled, }: {
     theme?: MaterialTheme;
+    enabled?: boolean;
 }): react.JSX.Element;
 
-interface LoaderOverlayProps {
-    phase: "loading" | "entering" | "idle" | "exiting";
-    cinemaName: string;
-    theme: MaterialTheme;
-    onEnter: () => void;
-    onThemeChange: (theme: MaterialTheme) => void;
+declare function ClickShockwave({ theme, enabled, }: {
+    theme?: MaterialTheme;
+    enabled?: boolean;
+}): react.JSX.Element | null;
+
+interface ElectricPlasmaProps {
+    theme?: MaterialTheme;
+    enabled?: boolean;
 }
-declare function LoaderOverlay({ phase, cinemaName, theme, onEnter, onThemeChange, }: LoaderOverlayProps): react.JSX.Element;
+declare function ElectricPlasma({ theme, enabled, }: ElectricPlasmaProps): react.JSX.Element | null;
 
 interface SceneParticlesProps {
     theme: MaterialTheme;
@@ -44,25 +91,31 @@ interface SceneParticlesProps {
 }
 declare function SceneParticles({ theme, visible }: SceneParticlesProps): react.JSX.Element | null;
 
-interface CinemaBackgroundProps {
-    text?: string;
-    theme?: MaterialTheme;
-    customBackground?: string;
-    interactiveSparks?: boolean;
-    showParticles?: boolean;
-    className?: string;
-    style?: React.CSSProperties;
-    children?: React.ReactNode;
+interface CameraRigProps {
+    phase: "loading" | "entering" | "idle" | "exiting";
 }
-/**
- * Reusable 3D Cinema Background Component.
- * Fits dynamically inside any parent container (div, header, section).
- */
-declare function CinemaBackground({ text, theme, customBackground, interactiveSparks, showParticles, className, style, children, }: CinemaBackgroundProps): react.JSX.Element;
+declare function CameraRig({ phase }: CameraRigProps): null;
+
+interface EffectState {
+    sparks: boolean;
+    shockwave: boolean;
+    plasma: boolean;
+    embers: boolean;
+}
+interface LoaderOverlayProps {
+    phase: "loading" | "entering" | "idle" | "exiting";
+    cinemaName: string;
+    theme: MaterialTheme;
+    effects: EffectState;
+    onTitleChange: (newTitle: string) => void;
+    onThemeChange: (theme: MaterialTheme) => void;
+    onToggleEffect: (effectName: keyof EffectState) => void;
+}
+declare function LoaderOverlay({ phase, cinemaName, theme, effects, onTitleChange, onThemeChange, onToggleEffect, }: LoaderOverlayProps): react.JSX.Element;
 
 declare function CinemaHome({ cinemaName, webTheme }: {
     cinemaName?: string;
     webTheme?: string;
 }): react.JSX.Element;
 
-export { AnimatedLetter, CameraRig, CinemaBackground, type CinemaBackgroundProps, CinemaHome, CinemaLoader, ClickFireSparks, LoaderOverlay, type MaterialTheme, SceneParticles };
+export { AnimatedLetter, CameraRig, CinemaBackground, type CinemaBackgroundProps, CinemaHome, CinemaLoader, ClickFireSparks, ClickShockwave, type EffectState, ElectricPlasma, LoaderOverlay, type MaterialTheme, SceneParticles, type WithCinema3DOptions, withCinema3D };