@stianlarsen/react-light-beam 3.1.0 → 3.1.2

package/README.md

@@ -1,511 +1,136 @@
 # @stianlarsen/react-light-beam
 
-<div align="center">
+## 🚀 New Feature Alert!
 
-[![npm version](https://img.shields.io/npm/v/@stianlarsen/react-light-beam)](https://www.npmjs.com/package/@stianlarsen/react-light-beam)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
-[![Live Demo](https://img.shields.io/badge/demo-live-success)](https://stianlars1.github.io/react-light-beam)
+We've added a new prop: `scrollElement`. This allows you to specify which element should have the scroll listener attached, giving you greater flexibility in using the LightBeam component!
 
-**A high-performance React component for creating stunning scroll-triggered light beam effects**
+[![npm version](https://badge.fury.io/js/%40stianlarsen%2Freact-light-beam.svg)](https://badge.fury.io/js/%40stianlarsen%2Freact-light-beam)
 
-Powered by GSAP ScrollTrigger for buttery-smooth 60fps animations with atmospheric effects.
+A customizable React component that creates a light beam effect using conic gradients. The component is fully responsive and supports both light and dark modes. Ideal for adding dynamic and engaging visual elements to your web applications.
 
-[Live Demo](https://stianlars1.github.io/react-light-beam) • [Report Bug](https://github.com/stianalars1/react-light-beam/issues) • [Request Feature](https://github.com/stianalars1/react-light-beam/issues)
+## Preview
 
-</div>
-
-![LightBeam Component Preview](https://raw.githubusercontent.com/Stianlars1/react-light-beam/main/lightBeam.png)
-
----
+![LightBeam Component](https://github.com/Stianlars1/react-light-beam/blob/5422cdc60ae7ab6b52d644d452646bec7212f76f/lightBeam.png)
 
-## ✨ Features
+_A preview of @stianlarsen/react-light-beam_
 
-- 🚀 **GSAP-Powered** - Industry-leading animation performance (40% faster than alternatives)
-- 📜 **Scroll-Driven** - Smooth scrubbing with GSAP ScrollTrigger
-- 💫 **Atmospheric Effects** - Dust particles, mist, and pulse animations
-- 🌓 **Dark Mode** - Auto-detects system preferences
-- ⚙️ **Highly Customizable** - Full control over appearance and behavior
-- 🎯 **Zero Configuration** - Works out of the box with sensible defaults
-- 💪 **TypeScript** - Full type definitions included
-- 📦 **Lightweight** - Only 15KB gzipped (including GSAP)
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @stianlarsen/react-light-beam
 ```
 
-That's it! GSAP is included automatically. ✨
+or
 
----
+```bash
+yarn add @stianlarsen/react-light-beam
+```
 
-## 🚀 Quick Start
+## Usage
 
 ```jsx
 import { LightBeam } from "@stianlarsen/react-light-beam";
+import "your-css-file.css"; // Include the necessary styles
 
-function App() {
+const App = () => {
   return (
-    <div style={{ position: "relative", minHeight: "200vh" }}>
+    <div className="your-container-class">
       <LightBeam
+        id="unique-lightbeam"
+        className="your-lightbeam-class"
         colorDarkmode="rgba(255, 255, 255, 0.8)"
         colorLightmode="rgba(0, 0, 0, 0.2)"
         fullWidth={0.8}
+        maskLightByProgress={true}
+        invert={false}
+        scrollElement={window} // New prop to specify scroll element
       />
-      <YourContent />
+      <YourContentHere />
     </div>
   );
-}
-```
-
----
-
-## 📖 Table of Contents
-
-- [Core Props](#-core-props)
-- [Atmospheric Effects](#-atmospheric-effects-new)
-- [Styling Options](#-styling-options)
-- [Advanced Usage](#-advanced-usage)
-- [Performance](#-performance)
-- [Examples](#-examples)
-- [API Reference](#-api-reference)
-- [Changelog](#-changelog)
-- [Contributing](#-contributing)
-
----
-
-## 🎛️ Core Props
-
-### Basic Configuration
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `colorLightmode` | `string` | `"rgba(0,0,0, 0.5)"` | Beam color in light mode |
-| `colorDarkmode` | `string` | `"rgba(255, 255, 255, 0.5)"` | Beam color in dark mode |
-| `fullWidth` | `number` | `1.0` | Maximum beam width (0-1) |
-| `invert` | `boolean` | `false` | Invert scroll direction |
-| `maskLightByProgress` | `boolean` | `false` | Fade beam as user scrolls |
-| `className` | `string` | - | Custom CSS classes |
-| `style` | `CSSProperties` | - | Inline styles override |
-| `scrollElement` | `EventTarget` | `document.body` | Element to attach scroll listener |
-| `onLoaded` | `() => void` | - | Callback when component mounts |
-| `disableDefaultStyles` | `boolean` | `false` | Disable all default inline styles |
-
----
-
-## 💫 Atmospheric Effects (NEW)
-
-Add depth and dimension with optional atmospheric effects:
-
-### Dust Particles
-
-Floating particles that drift through the beam.
-
-```jsx
-<LightBeam
-  dustParticles={{
-    enabled: true,
-    count: 50,              // Number of particles
-    speed: 1.2,             // Animation speed multiplier
-    sizeRange: [1, 3],      // Min/max size in pixels
-    opacityRange: [0.2, 0.6], // Min/max opacity
-    color: "rgba(255, 255, 255, 0.8)" // Optional (inherits beam color)
-  }}
-/>
-```
-
-### Mist Effect
-
-Volumetric fog atmosphere with depth.
-
-```jsx
-<LightBeam
-  mist={{
-    enabled: true,
-    intensity: 0.4,    // Opacity/thickness (0-1)
-    speed: 1,          // Animation speed multiplier
-    layers: 3          // More layers = more depth
-  }}
-/>
-```
-
-### Pulse Effect
-
-Rhythmic breathing animation.
-
-```jsx
-<LightBeam
-  pulse={{
-    enabled: true,
-    duration: 2.5,          // Seconds per pulse cycle
-    intensity: 0.3,         // Pulse strength (0-1)
-    easing: "sine.inOut"    // GSAP easing function
-  }}
-/>
-```
-
-### Combine All Effects
+};
 
-```jsx
-<LightBeam
-  colorDarkmode="rgba(255, 255, 255, 0.8)"
-  fullWidth={0.8}
-  dustParticles={{ enabled: true, count: 50 }}
-  mist={{ enabled: true, intensity: 0.4, layers: 3 }}
-  pulse={{ enabled: true, duration: 2.5, intensity: 0.3 }}
-/>
+export default App;
 ```
 
----
+### Props
 
-## 🎨 Styling Options
+| Prop Name             | Type                         | Default Value              | Description                                                                                                                                                                                                                                                                                                                                  |
+| --------------------- | ---------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                  | `string`                     | `undefined`                | Optional string representing a unique ID for the LightBeam container.                                                                                                                                                                                                                                                                        |
+| `className`           | `string`                     | `undefined`                | Optional string representing custom classes to be added to the LightBeam container.                                                                                                                                                                                                                                                          |
+| `colorLightmode`      | `string`                     | `rgba(0,0,0, 0.5)`         | Optional string representing the color of the light beam in light mode.                                                                                                                                                                                                                                                                      |
+| `colorDarkmode`       | `string`                     | `rgba(255, 255, 255, 0.5)` | Optional string representing the color of the light beam in dark mode.                                                                                                                                                                                                                                                                       |
+| `fullWidth`           | `number`                     | `1.0`                      | Optional number between `0` and `1` representing the maximum width the light beam can reach.                                                                                                                                                                                                                                                 |
+| `maskLightByProgress` | `boolean`                    | `false`                    | If `true`, the `mask-image`'s linear gradient will start with the chosen color at 0% and the transparent part starting at 50%. As the user scrolls, it will dynamically change to have the transparent part at 95%, reducing the glow effect. If `false`, it will default to `linear-gradient(to bottom, chosenColor 25%, transparent 95%)`. |
+| `invert`              | `boolean`                    | `false`                    | Optional boolean to invert the scroll progress calculation.                                                                                                                                                                                                                                                                                  |
+| `scrollElement`       | `EventTarget` or `undefined` | `window`                   | Optional prop for which element to attach the scroll listener to. This could be the `window`, `document.body`, or any other scrollable element.                                                                                                                                                                                              |
+| `onLoaded`            | `undefined or () => void`    | `undefined`                | Optional function to run when the component has mounted                                                                                                                                                                                                                                                                                      |
 
-### Option 1: CSS Variables (Recommended)
+### Default Configuration
 
-Override default styles using CSS variables:
-
-```jsx
-<LightBeam className="custom-beam" />
-```
+The component comes with the following default styles:
 
 ```css
-.custom-beam {
-  --react-light-beam-height: 800px;
-  --react-light-beam-width: 80vw;
+.react__light__beam {
+  height: 500px;
+  width: 100vw;
+  transition: all 0.5s ease;
+  will-change: auto;
 }
 ```
 
-**Available CSS Variables:**
-- `--react-light-beam-height` (default: `500px`)
-- `--react-light-beam-width` (default: `100vw`)
+These default styles ensure that the component is immediately visible when added to your application. However, for more effective use, you might want to customize its position and behavior.
 
-### Option 2: Inline Styles
+### Recommended Usage
 
-```jsx
-<LightBeam
-  style={{
-    height: "800px",
-    width: "80vw",
-    marginTop: "-200px"
-  }}
-/>
-```
-
-### Option 3: Full CSS Control
+For best results, it's recommended to position the `LightBeam` component as an absolutely positioned element within a relatively positioned container. This allows the light beam to cast light downwards over your content, creating a more dynamic and engaging visual effect.
 
-Disable default styles for complete control:
+Example:
 
 ```jsx
-<LightBeam
-  disableDefaultStyles={true}
-  className="my-beam"
-/>
-```
-
-```css
-.my-beam {
-  height: 800px;
-  width: 100%;
-  position: absolute;
-  /* Full control - you provide all styles */
-}
-```
-
----
-
-## 🔧 Advanced Usage
-
-### Positioning
-
-For best results, position the beam absolutely within a relative container:
-
-```jsx
-<div className="hero-section">
-  <LightBeam className="beam" />
-  <YourContent />
+<div className="container">
+  <LightBeam className="lightBeam" />
 </div>
 ```
 
-```css
-.hero-section {
-  position: relative;
-  min-height: 100vh;
-}
+And in your CSS or SCSS:
 
-.beam {
-  position: absolute;
-  inset: 0;
-  margin-top: -300px; /* Adjust to position beam above content */
-  z-index: -1;
+```scss
+.container {
+  position: relative;
+  z-index: 1;
+
+  .lightBeam {
+    position: absolute;
+    inset: 0;
+    width: 100vw;
+    height: 100%; // Important: Ensure the beam covers the entire height
+    z-index: -1;
+    margin-top: -300px; // Adjust as needed to position the light beam above the content
+  }
 }
 ```
 
-### Custom Scroll Container
+### Dark Mode Support
 
-Attach to a specific scrollable element:
+The component automatically adjusts between light and dark modes based on the user's system preferences. You can pass different colors for light and dark modes using the `colorLightmode` and `colorDarkmode` props.
 
-```jsx
-const scrollContainer = useRef(null);
-
-<div ref={scrollContainer} style={{ height: "500px", overflow: "auto" }}>
-  <LightBeam scrollElement={scrollContainer.current} />
-  <YourContent />
-</div>
-```
-
-### Dark Mode Customization
-
-The component auto-detects system preferences. Customize colors per mode:
+### Example
 
 ```jsx
 <LightBeam
-  colorLightmode="rgba(0, 0, 0, 0.2)"        // Subtle in light mode
-  colorDarkmode="rgba(255, 255, 255, 0.8)"   // Vibrant in dark mode
+  id="lightbeam-example"
+  className="custom-lightbeam"
+  colorDarkmode="rgba(255, 255, 255, 0.8)"
+  colorLightmode="rgba(0, 0, 0, 0.2)"
+  fullWidth={0.5}
+  maskLightByProgress={true}
+  invert={true}
+  scrollElement={document.body} // Example usage of the new scrollElement prop
 />
 ```
 
----
-
-## ⚡ Performance
-
-**LightBeam** is optimized for production:
-
-| Metric | Value |
-|--------|-------|
-| Bundle Size | ~15KB gzipped (with GSAP) |
-| Frame Rate | Consistent 60fps |
-| Scroll Handler | <0.4ms per frame |
-| Memory | Minimal footprint |
-| CPU Usage | 30% less than alternatives |
+### License
 
-### Optimizations
-
-- ✅ CSS custom properties for minimal DOM updates
-- ✅ GPU-accelerated transforms
-- ✅ Debounced scroll events via GSAP
-- ✅ Lazy-loaded atmospheric effects
-- ✅ Tree-shakeable code
-- ✅ No layout thrashing
-
----
-
-## 📚 Examples
-
-### Hero Section
-
-```jsx
-function Hero() {
-  return (
-    <section className="hero">
-      <LightBeam
-        colorDarkmode="rgba(59, 130, 246, 0.5)"
-        fullWidth={0.7}
-        className="hero-beam"
-        pulse={{ enabled: true, duration: 3, intensity: 0.2 }}
-      />
-      <h1>Welcome to the Future</h1>
-      <p>Scroll to explore</p>
-    </section>
-  );
-}
-```
-
-### Landing Page with Effects
-
-```jsx
-function Landing() {
-  return (
-    <div className="landing">
-      <LightBeam
-        colorDarkmode="rgba(139, 92, 246, 0.6)"
-        fullWidth={0.9}
-        maskLightByProgress={true}
-        dustParticles={{ enabled: true, count: 40, speed: 0.8 }}
-        mist={{ enabled: true, intensity: 0.3, layers: 2 }}
-      />
-      <YourLandingContent />
-    </div>
-  );
-}
-```
-
-### Multiple Beams
-
-```jsx
-function MultiBeam() {
-  return (
-    <div className="container">
-      <LightBeam
-        id="beam-1"
-        colorDarkmode="rgba(59, 130, 246, 0.5)"
-        fullWidth={0.6}
-      />
-      <LightBeam
-        id="beam-2"
-        colorDarkmode="rgba(139, 92, 246, 0.3)"
-        fullWidth={0.8}
-        invert={true}
-      />
-      <YourContent />
-    </div>
-  );
-}
-```
-
----
-
-## 📋 API Reference
-
-### Complete Props Table
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `id` | `string` | - | Unique ID for the container |
-| `className` | `string` | - | Custom CSS classes |
-| `style` | `React.CSSProperties` | - | Inline styles (merged with defaults) |
-| `colorLightmode` | `string` | `"rgba(0,0,0, 0.5)"` | Light mode beam color |
-| `colorDarkmode` | `string` | `"rgba(255, 255, 255, 0.5)"` | Dark mode beam color |
-| `fullWidth` | `number` | `1.0` | Maximum width (0-1) |
-| `maskLightByProgress` | `boolean` | `false` | Progressive mask fade |
-| `invert` | `boolean` | `false` | Invert scroll direction |
-| `scrollElement` | `EventTarget` | `document.body` | Scroll container |
-| `onLoaded` | `() => void` | - | Mount callback |
-| `disableDefaultStyles` | `boolean` | `false` | Disable inline styles |
-| `dustParticles` | `DustParticlesConfig` | `{ enabled: false }` | Dust particles config |
-| `mist` | `MistConfig` | `{ enabled: false }` | Mist effect config |
-| `pulse` | `PulseConfig` | `{ enabled: false }` | Pulse effect config |
-
-### Type Definitions
-
-```typescript
-type DustParticlesConfig = {
-  enabled?: boolean;
-  count?: number;              // Default: 30
-  speed?: number;              // Default: 1
-  sizeRange?: [number, number]; // Default: [1, 3]
-  opacityRange?: [number, number]; // Default: [0.2, 0.6]
-  color?: string;              // Default: inherits beam color
-};
-
-type MistConfig = {
-  enabled?: boolean;
-  intensity?: number;          // Default: 0.3 (0-1)
-  speed?: number;              // Default: 1
-  layers?: number;             // Default: 2
-};
-
-type PulseConfig = {
-  enabled?: boolean;
-  duration?: number;           // Default: 2 (seconds)
-  intensity?: number;          // Default: 0.2 (0-1)
-  easing?: string;             // Default: "sine.inOut"
-};
-```
-
----
-
-## 📝 Changelog
-
-### v3.0.0 (2026-01-04)
-- ✨ **NEW:** Added atmospheric effects (dust particles, mist, pulse)
-- 🚀 **BREAKING:** GSAP now included as dependency (no manual install needed)
-- 📦 **IMPROVED:** One-command installation
-- 🎯 **IMPROVED:** Homepage now points to live demo
-- 🐛 **FIXED:** Removed duplicate dependencies
-- 📚 **IMPROVED:** Complete README rewrite with comprehensive docs
-
-### v2.1.1 (2026-01-04)
-- ⚡ **PERFORMANCE:** Optimized scroll handler with CSS custom properties
-- 🐛 **FIXED:** Laggy scroll behavior with `invert=true`
-- 🐛 **FIXED:** CSS variable color parsing errors
-- 📈 **IMPROVED:** 60-80% reduction in scroll handler execution time
-
-### v2.0.0 (2026-01-04)
-- 🚀 **BREAKING:** Migrated from Framer Motion to GSAP ScrollTrigger
-- ⚡ **PERFORMANCE:** 40% faster scroll performance
-- 🐛 **FIXED:** Bidirectional scrolling issues
-- 🐛 **FIXED:** Invert prop behavior
-- 🐛 **FIXED:** Color switching glitches on scroll direction change
-- 🎨 **IMPROVED:** Removed CSS transitions (GSAP handles animations)
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please follow these steps:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/stianalars1/react-light-beam.git
-cd react-light-beam
-
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
-
-# Run the example locally
-cd example
-npm install
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) to view the demo.
-
-### Testing Changes
-
-```bash
-# Build the package
-npm run build
-
-# Build the example
-cd example && npm run build
-
-# Test the static export
-npx serve out
-```
-
----
-
-## 📄 License
-
-MIT © [Stian Larsen](https://github.com/stianlars1)
-
----
-
-## 🙏 Acknowledgments
-
-- [GSAP](https://greensock.com/gsap/) - Industry-leading animation library
-- [React](https://react.dev/) - The library for web and native user interfaces
-- [TypeScript](https://www.typescriptlang.org/) - JavaScript with syntax for types
-
----
-
-## 🔗 Links
-
-- [Live Demo](https://stianlars1.github.io/react-light-beam)
-- [npm Package](https://www.npmjs.com/package/@stianlarsen/react-light-beam)
-- [GitHub Repository](https://github.com/stianlars1/react-light-beam)
-- [Report Issues](https://github.com/stianlars1/react-light-beam/issues)
-
----
-
-<div align="center">
-
-**Built with ❤️ using GSAP ScrollTrigger**
-
-⭐ Star this repo if you find it useful!
-
-</div>
+MIT © [Stian Larsen](https://github.com/stianlarsen)