reacthub-pixitweenjs 0.2.109-alpha.4 → 0.2.109-alpha.7

package/README.md

@@ -1,61 +1,421 @@
-<h1 align="center">
-  Welcome to Reacthub PixiTweenJS
-</h1>
+<div align="center">
 
-To install the component packages using NPM/ Yarn:
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/khanzzirfan/reacthub-pixitweenjs/main/src/assets/svg/pixitweenjs-logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/khanzzirfan/reacthub-pixitweenjs/main/src/assets/svg/pixitweenjs-logo.svg">
+  <img src="https://raw.githubusercontent.com/khanzzirfan/reacthub-pixitweenjs/main/src/assets/svg/pixitweenjs-logo.svg" alt="PixiTweenJS Logo" width="500">
+</picture>
 
-```js
-  npm install reacthub-pixitweenjs
+# ✨ Reacthub PixiTweenJS ✨
+
+**A powerful library for creating stunning animated, time-controlled canvas elements in React using PixiJS, GSAP, and more**
+
+[![npm version](https://img.shields.io/npm/v/reacthub-pixitweenjs.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/reacthub-pixitweenjs)
+[![npm downloads](https://img.shields.io/npm/dm/reacthub-pixitweenjs.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/reacthub-pixitweenjs)
+[![license](https://img.shields.io/npm/l/reacthub-pixitweenjs.svg?style=for-the-badge)](LICENSE.md)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)](https://reactjs.org/)
+[![PixiJS](https://img.shields.io/badge/PixiJS-4A90E2?style=for-the-badge&logo=pixijs&logoColor=white)](https://pixijs.com/)
+[![GSAP](https://img.shields.io/badge/GSAP-88CE02?style=for-the-badge&logo=gsap&logoColor=white)](https://greensock.com/gsap/)
+
+<br>
+
+<pre>
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║                                                                               ║
+║      ██████╗ ██╗██╗  ██╗██╗████████╗███████╗██╗    ██╗███████╗██████╗ ███╗   ║
+║      ██╔══██╗██║╚██╗██╔╝██║╚══██╔══╝██╔════╝██║    ██║██╔════╝██╔══██╗████╗  ║
+║      ██████╔╝██║ ╚███╔╝ ██║   ██║   █████╗  ██║ █╗ ██║█████╗  ██████╔╝██╔██╗ ║
+║      ██╔═══╝ ██║ ██╔██╗ ██║   ██║   ██╔══╝  ██║███╗██║██╔══╝  ██╔══██╗██║╚██╗║
+║      ██║     ██║██╔╝ ██╗██║   ██║   ███████╗╚███╔███╔╝███████╗██║  ██║██║ ╚█║║
+║      ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝ ╚══╝╚══╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝║
+║                                                                               ║
+║         🎬 Timeline-based animations  |  ⚡ WebGL powered  |  🎨 Interactive  ║
+║                                                                               ║
+╚═══════════════════════════════════════════════════════════════════════════════╝
+</pre>
+
+**[📖 Documentation](https://pixitweenjs.xyz/)** • **[🎮 Live Demo](https://pixitweenjs.xyz/)** • **[💬 Issues](https://github.com/khanzzirfan/reacthub-pixitweenjs/issues)** • **[🤝 Contributing](Contribution.md)**
+
+</div>
+
+---
+
+## 🌟 **Features**
+
+<div align="center">
+
+|           Feature            | Description                                         |
+| :--------------------------: | --------------------------------------------------- |
+|   🎬 **Timeline Control**    | Precise start/end time control for all elements     |
+|   ⚡ **High Performance**    | WebGL-accelerated rendering with PixiJS             |
+|  🎨 **Rich Media Support**   | Images, Videos, Audio, GIFs, SVG, Lottie animations |
+|   ✏️ **Interactive Text**    | Advanced typography with custom styling & effects   |
+|   🔄 **GSAP Integration**    | Professional-grade animations & transitions         |
+| 🎛️ **Visual Transformation** | Drag, rotate, scale with intuitive transformer      |
+|   🎨 **Color Correction**    | Temperature, HSL, blur, vignette & more filters     |
+|   🎭 **Particle Effects**    | Build stunning visual effects                       |
+|  🔊 **Audio Visualization**  | Real-time waveform rendering                        |
+|      📱 **Responsive**       | Works seamlessly across devices                     |
+|      🔧 **TypeScript**       | Full type safety & IntelliSense                     |
+|      🎯 **Composable**       | Modular components for flexibility                  |
+
+</div>
+
+---
+
+## 🚀 **Quick Start**
+
+### Installation
+
+```bash
+npm install reacthub-pixitweenjs
 ```
 
-```js
-  yarn add reacthub-pixitweenjs
+or
+
+```bash
+yarn add reacthub-pixitweenjs
 ```
 
-Make sure you install the devDependencies in your project.
+### Required Dependencies
+
+Make sure to install these peer dependencies:
 
-```js
-npm install
-    "@pixi/gif": "^2.1.0",
-    "@pixi/react": "~7.1.0",
-    "@pixi/sound": "^5.2.1",
-    "pixi-filters": "^5.2.1",
-    "pixi-svg": "^3.2.0",
-    "pixi.js": "^7.2.3",
-    "gsap": "3.11.5",
-    "howler": "^2.2.3",
-    "lottie-web": "^5.10.2",
-    "react-custom-events": "^1.1.1",
+```bash
+npm install \
+  @pixi/gif@^2.1.0 \
+  @pixi/react@~7.1.0 \
+  @pixi/sound@^5.2.1 \
+  pixi-filters@^5.2.1 \
+  pixi-svg@^3.2.0 \
+  pixi.js@^7.2.3 \
+  gsap@3.11.5 \
+  howler@^2.2.3 \
+  lottie-web@^5.10.2 \
+  react-custom-events@^1.1.1 \
+  react@^18.2.0 \
+  react-dom@^18.2.0
 ```
 
-## Description
+### Basic Example
+
+```tsx
+import React from "react";
+import { GsapPixieContextProvider } from "reacthub-pixitweenjs";
+import { PixiStage } from "reacthub-pixitweenjs";
+import { PixiSequence } from "reacthub-pixitweenjs";
+import { PixiImageSprite } from "reacthub-pixitweenjs";
+
+function MyAnimatedScene() {
+  return (
+    <GsapPixieContextProvider>
+      <PixiStage
+        width={1920}
+        height={1080}
+        options={{ backgroundColor: 0x2d2e3c }}
+      >
+        <PixiSequence startAt={0} endAt={10}>
+          <PixiImageSprite
+            uniqueId="hero-image"
+            src="https://example.com/image.jpg"
+            transformation={{
+              x: 960,
+              y: 540,
+              width: 800,
+              height: 600,
+              anchor: 0.5,
+              alpha: 1,
+            }}
+            startAt={0}
+            endAt={10}
+          />
+        </PixiSequence>
+      </PixiStage>
+    </GsapPixieContextProvider>
+  );
+}
+```
+
+---
+
+## 🎯 **Core Components**
+
+### 🖼️ **PixiImageSprite**
+
+Display images with advanced transformations and filters.
+
+```tsx
+<PixiImageSprite
+  src="path/to/image.jpg"
+  transformation={{
+    x: 100,
+    y: 100,
+    width: 400,
+    height: 300,
+    anchor: 0.5,
+    rotation: 0,
+    alpha: 1,
+    scale: 1,
+    colorCorrection: {
+      temperature: 6500,
+      contrast: 1,
+      saturation: 1,
+      blurRadius: 0,
+    },
+  }}
+  startAt={0}
+  endAt={5}
+/>
+```
+
+### 🎬 **PixiVideoSprite**
+
+Seamlessly integrate video with GSAP timeline synchronization.
+
+```tsx
+<PixiVideoSprite
+  src="path/to/video.mp4"
+  transformation={{ x: 0, y: 0, width: 1920, height: 1080, anchor: 0 }}
+  startAt={0}
+  endAt={30}
+/>
+```
+
+### 🎵 **PixiAudioSprite**
+
+Audio playback with real-time visualization support.
+
+```tsx
+<PixiAudioSprite
+  src="path/to/audio.mp3"
+  startAt={0}
+  endAt={20}
+  showWaveform={true}
+/>
+```
+
+### ✏️ **PixiTextSprite**
+
+Rich typography with custom fonts, colors, and effects.
+
+```tsx
+<PixiTextSprite
+  text="Hello, World!"
+  transformation={{
+    x: 500,
+    y: 300,
+    width: 400,
+    height: 100,
+    anchor: 0.5,
+    fontSize: 48,
+    fontFamily: "Arial",
+    fill: 0xffffff,
+    stroke: 0x000000,
+    strokeThickness: 2,
+  }}
+  startAt={0}
+  endAt={10}
+/>
+```
+
+### 🎨 **PixiSVGSprite**
+
+Vector graphics with full transformation support.
+
+```tsx
+<PixiSVGSprite
+  svgPath="M10,10 L100,10 L100,100 Z"
+  fill={0xff5733}
+  transformation={{ x: 200, y: 200, width: 100, height: 100, anchor: 0.5 }}
+  startAt={0}
+  endAt={10}
+/>
+```
+
+### 🎪 **PixiGifSprite & PixiLottieSprite**
+
+Animated GIFs and Lottie animations.
+
+```tsx
+<PixiGifSprite
+  src="animation.gif"
+  transformation={{ x: 400, y: 400, width: 200, height: 200, anchor: 0.5 }}
+  startAt={0}
+  endAt={15}
+/>
+
+<PixiLottieSprite
+  src="animation.json"
+  transformation={{ x: 600, y: 400, width: 300, height: 300, anchor: 0.5 }}
+  startAt={0}
+  endAt={10}
+/>
+```
+
+### 🔄 **PixiSequence**
+
+Time-based composition and sequencing.
+
+```tsx
+<PixiSequence startAt={0} endAt={30}>
+  <PixiImageSprite ... />
+  <PixiTextSprite ... />
+  <PixiVideoSprite ... />
+</PixiSequence>
+```
+
+### 🎛️ **PixiTransformer**
+
+Interactive element manipulation with visual handles.
+
+```tsx
+<PixiTransformer
+  pixiTransformerRef={transformerRef}
+  imageRef={imageRef}
+  transformCommit={handleTransform}
+  transformChange={handleChange}
+/>
+```
+
+---
+
+## 🎨 **Advanced Features**
+
+### 🎞️ Timeline Composition
+
+Create complex animations with precise timing:
+
+```tsx
+<PixiSequenceWrapper startAt={0} endAt={30}>
+  {/* Intro Sequence */}
+  <PixiSequence startAt={0} endAt={5}>
+    <PixiImageSprite startAt={0} endAt={5} ... />
+  </PixiSequence>
+
+  {/* Main Content */}
+  <PixiSequence startAt={5} endAt={25}>
+    <PixiVideoSprite startAt={5} endAt={25} ... />
+    <PixiTextSprite startAt={10} endAt={20} ... />
+  </PixiSequence>
+
+  {/* Outro Sequence */}
+  <PixiSequence startAt={25} endAt={30}>
+    <PixiImageSprite startAt={25} endAt={30} ... />
+  </PixiSequence>
+</PixiSequenceWrapper>
+```
+
+### 🎨 Color Correction & Effects
+
+Professional-grade image manipulation:
+
+```tsx
+transformation={{
+  colorCorrection: {
+    temperature: 6500,    // White balance
+    contrast: 1.2,        // Contrast adjustment
+    saturation: 1.5,      // Color saturation
+    exposure: 0,          // Brightness exposure
+    hue: 0,              // Hue shift
+    blurRadius: 0,       // Gaussian blur
+    sharpness: 1,        // Edge sharpness
+    vignette: 0          // Vignette effect
+  },
+  effect: {
+    // Add particle effects, glows, etc.
+  }
+}}
+```
+
+### 🔄 GSAP Animation Integration
+
+Leverage the full power of GSAP:
+
+```tsx
+const { tl } = useContext(GsapPixieContext);
+
+// Access the master timeline
+tl.to(spriteRef, {
+  x: 1000,
+  y: 500,
+  rotation: 360,
+  duration: 5,
+});
+```
+
+---
+
+## 📚 **Documentation & Resources**
+
+- **[📖 Complete Documentation](https://pixitweenjs.xyz/)** - Interactive Storybook docs
+- **[🎮 Live Playground](https://pixitweenjs.xyz/)** - Try it online
+- **[💡 Installation Guide](https://pixitweenjs.xyz/?path=/docs/getting-started-installation--docs)**
+- **[🎬 Examples](https://pixitweenjs.xyz/?path=/docs/components-imagesprite--docs)**
+
+---
+
+## 🤝 **Contributing**
+
+We welcome contributions! Please read our [Contributing Guide](Contribution.md) before submitting PRs.
+
+---
+
+## 📄 **License**
+
+This library is licensed under the **Apache License 2.0** with additional terms. See [LICENSE.md](LICENSE.md) for complete terms.
+
+> **📋 Quick Reference:** Apache 2.0 is an open-source license that allows commercial use, modification, distribution, patent use, private use, and sublicensing. See the full license for all terms and additional restrictions.
+
+### What You Can Do
+
+✅ **Permitted:**
+
+- ✅ Commercial use in any project
+- ✅ Modify and adapt the code
+- ✅ Distribute and sublicense
+- ✅ Private and internal use
+- ✅ Patent grant included
+- ✅ Place warranty
+
+❌ **Additional Restrictions:**
+
+- ❌ Must include copyright notice
+- ❌ Cannot remove attribution
+- ❌ Must include license file
+- ❌ Commercial deployments should notify author
+
+### Commercial Use
+
+Apache 2.0 allows commercial use. However, for large-scale enterprise deployments or white-label products, we recommend contacting **reacthub.ai@gmail.com** to discuss licensing options and potential support arrangements.
 
-PixiTweenJs is designed to help you build animated time-controlled canvas elements on web apps using extensible Pixijs Components underneath. The package composes the reacthub/pixitweenjs Web Component package. You can use these Web Components flexibly, either from npm packages, from the CDN, or you can bring it into your project to customize and extend it.
+---
 
-## Usage
+## 🌟 **Inspired By**
 
-Visit the [storybook](https://pixitweenjs.xyz/)
+- **[editly](https://github.com/mifi/editly)** - Declarative video API
+- **[remotion](https://github.com/remotion-dev/remotion)** - Create videos with React
 
-## Documentation
+---
 
-## License
+## 📊 **Stats**
 
-This library is licensed under the MIT License. See the LICENSE.md file for details.
+<div align="center">
 
-Note: This library comes with restrictions. You are not allowed to copy, modify, or sell this library or any derivative work on behalf of the original author. Usage is permitted only under the terms specified in the license.
+![GitHub stars](https://img.shields.io/github/stars/khanzzirfan/reacthub-pixitweenjs?style=for-the-badge&logo=github)
+![GitHub forks](https://img.shields.io/github/forks/khanzzirfan/reacthub-pixitweenjs?style=for-the-badge&logo=github)
+![GitHub issues](https://img.shields.io/github/issues/khanzzirfan/reacthub-pixitweenjs?style=for-the-badge&logo=github)
 
-For example:
+</div>
 
-- Allowed: Use in personal and non-commercial projects.
-- Not Allowed: Copying, modification, or commercial use without explicit permission.
+---
 
-## Contributing
+<div align="center">
 
-Want to contribute to pixitweenjs? Our [contributing guide](Contribution.md) has you covered.
+### **Made with ❤️ in 🇦🇺 Australia**
 
-## See also
+**Built for developers who create beautiful, interactive experiences**
 
-- [editly](https://github.com/mifi/editly) - Declarative video API I also created earlier
-- [remotion](https://github.com/remotion-dev/remotion) - Great inspiration
+[⬆ Back to Top](#-reacthub-pixitweenjs-)
 
-Made with ❤️ in 🇦🇺
+</div>

package/dist/assets/icon/transformericons/icons.d.ts

@@ -0,0 +1,8 @@
+export declare const opacityIcon: () => string;
+export declare const roundCornersIcon: () => string;
+export declare const deleteIcon: () => string;
+export declare const copyIcon: () => string;
+export declare const orderIcon: () => string;
+export declare const saveIcon: () => string;
+export declare const replaceImageIcon: () => string;
+export declare const chevronRightIcon: () => string;

package/dist/components/PixiAudioSprite/PixiAudioSprite.d.ts

@@ -1,5 +1,6 @@
 import { PixiBaseSpriteProps, ForwardedRefResponse } from '../../types/BaseProps';
 import * as React from "react";
+import * as PIXI from "pixi.js";
 export interface PixiAudioSpriteProps extends PixiBaseSpriteProps {
     uniqueId: string;
     src: string;
@@ -10,6 +11,8 @@ export interface PixiAudioSpriteProps extends PixiBaseSpriteProps {
     mute: boolean;
     speed: number;
     visible: boolean;
+    onContainerRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
+    onSpriteRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
 }
 declare const PixiAudioSprite: React.ForwardRefExoticComponent<PixiAudioSpriteProps & React.RefAttributes<ForwardedRefResponse | null>>;
 export default PixiAudioSprite;

package/dist/components/PixiAudioSprite/PixiAudioSprite.stories.d.ts

@@ -1,101 +1,7 @@
-import { StoryObj } from '@storybook/react';
-import { Waveforms } from '../../types/Effects';
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { PixiAudioSprite } from '.';
 
-declare const meta: {
-    title: string;
-    component: import('react').ForwardRefExoticComponent<import('./PixiAudioSprite').PixiAudioSpriteProps & import('react').RefAttributes<import('../..').ForwardedRefResponse | null>>;
-    decorators: ((Story: any) => import("react/jsx-runtime").JSX.Element)[];
-    tags: string[];
-    argTypes: {
-        uniqueId: {
-            control: string;
-            description: string;
-        };
-        src: {
-            control: string;
-            description: string;
-        };
-        startAt: {
-            control: string;
-            description: string;
-        };
-        endAt: {
-            control: string;
-            description: string;
-        };
-        audioStartAt: {
-            control: string;
-            description: string;
-        };
-        audioEndAt: {
-            control: string;
-            description: string;
-        };
-        mute: {
-            control: string;
-            description: string;
-        };
-        speed: {
-            control: string;
-            description: string;
-        };
-        visible: {
-            control: string;
-            description: string;
-        };
-        transformation: {
-            control: string;
-            description: string;
-            x: {
-                control: string;
-                description: string;
-            };
-            y: {
-                control: string;
-                description: string;
-            };
-            width: {
-                control: string;
-                description: string;
-            };
-            height: {
-                control: string;
-                description: string;
-            };
-            anchor: {
-                control: string;
-                description: string;
-            };
-            rotation: {
-                control: string;
-                description: string;
-            };
-            alpha: {
-                control: string;
-                min: number;
-                max: number;
-                description: string;
-            };
-            scale: {
-                control: string;
-                description: string;
-            };
-            tint: {
-                control: string;
-                description: string;
-            };
-            blendMode: {
-                control: string;
-                description: string;
-            };
-            waveform: {
-                type: string;
-                options: Waveforms[];
-                description: string;
-            };
-        };
-    };
-};
+declare const meta: Meta<typeof PixiAudioSprite>;
 export default meta;
 type Story = StoryObj<typeof meta>;
 export declare const Normal: Story;
@@ -103,3 +9,4 @@ export declare const Visualization: Story;
 export declare const Speech: Story;
 export declare const Muted: Story;
 export declare const SplitPosition: Story;
+export declare const WithUnifiedTransformer: Story;

package/dist/components/PixiGifSprite/PixiGifGsapSync.d.ts

@@ -1,5 +1,6 @@
 import { PixiBaseSpriteProps, ForwardedRefResponse } from '../../types/BaseProps';
 import * as React from "react";
+import * as PIXI from "pixi.js";
 export interface PixiGifSpriteProps extends PixiBaseSpriteProps {
     uniqueId: string;
     src: string;
@@ -9,6 +10,8 @@ export interface PixiGifSpriteProps extends PixiBaseSpriteProps {
     frameEndAt: number;
     locked: boolean;
     loop: boolean;
+    onContainerRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
+    onSpriteRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
 }
 /**
  * PixiGifSprite Component is used to render gif image

package/dist/components/PixiGifSprite/PixiGifSprite.stories.d.ts

@@ -1,21 +1,22 @@
-import { StoryObj } from '@storybook/react';
+import { StoryObj } from '@storybook/react-vite';
 
+import * as React from "react";
 declare const meta: {
     title: string;
-    component: import('react').ForwardRefExoticComponent<import('./PixiGifGsapSync').PixiGifSpriteProps & import('react').RefAttributes<import('../../types').ForwardedRefResponse | null>>;
+    component: React.ForwardRefExoticComponent<import('./PixiGifGsapSync').PixiGifSpriteProps & React.RefAttributes<import('../..').ForwardedRefResponse | null>>;
     decorators: ((Story: any) => import("react/jsx-runtime").JSX.Element)[];
     tags: string[];
     argTypes: {
         uniqueId: {
-            control: string;
+            control: "text";
             description: string;
         };
         src: {
-            control: string;
+            control: "text";
             description: string;
         };
         transformation: {
-            control: string;
+            control: "object";
             description: string;
             x: {
                 control: string;
@@ -81,27 +82,27 @@ declare const meta: {
             };
         };
         applyTransformer: {
-            control: string;
+            control: "boolean";
             description: string;
         };
         startAt: {
-            control: string;
+            control: "number";
             description: string;
         };
         endAt: {
-            control: string;
+            control: "number";
             description: string;
         };
         frameStartAt: {
-            control: string;
+            control: "number";
             description: string;
         };
         frameEndAt: {
-            control: string;
+            control: "number";
             description: string;
         };
         visible: {
-            control: string;
+            control: "boolean";
             description: string;
         };
         onAnchorTransformationEnd: {
@@ -140,6 +141,14 @@ declare const meta: {
             action: string;
             description: string;
         };
+        onContainerRefReady: {
+            action: string;
+            description: string;
+        };
+        onSpriteRefReady: {
+            action: string;
+            description: string;
+        };
     };
 };
 export default meta;
@@ -151,3 +160,4 @@ export declare const Filters: Story;
 export declare const SplitPosition: Story;
 export declare const SplitStartPos: Story;
 export declare const StipopGif: Story;
+export declare const WithUnifiedTransformer: Story;