exodeui 2.4.0 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
-# exodeui
+# ExodeUI React SDK
 
-The React Runtime for the ExodeUI Animation Engine. Easily render and interact with ExodeUI animations in your React applications.
+The official React Runtime for the **ExodeUI Animation Engine**. Seamlessly render and interact with high-performance animations, physics simulations, and state machines built with ExodeUI.
 
 ## Installation
 
@@ -17,10 +17,9 @@ import { ExodeUICanvas } from 'exodeui';
 
 function App() {
   return (
-    <div style={{ width: 500, height: 500 }}>
-      {/* Option 1: Load from a URL or file path (e.g. in public folder) */}
+    <div style={{ width: 800, height: 600 }}>
       <ExodeUICanvas 
-        src="/my-animation.json"
+        src="/animations/my-scene.json"
         autoPlay={true}
         fit="Contain"
         alignment="Center"
@@ -30,83 +29,93 @@ function App() {
 }
 ```
 
-### Loading via Import
+## Features
 
-Alternatively, you can import the JSON directly if your bundler supports it:
+### 1. State Machine & Logic
+ExodeUI supports complex interactive logic using a node-based **State Machine**.
+- **Inputs**: Control the flow with Boolean, Number, and Trigger inputs.
+- **Logic Nodes**: Combine inputs using AND, OR, NOT, XOR.
+- **Conditions**: Create transitions based on input values (e.g., `Speed > 10`, `IsHovered == true`).
 
 ```tsx
-import { ExodeUICanvas } from 'exodeui';
-import animationData from './my-animation.json';
+const [engine, setEngine] = useState<ExodeUIEngine | null>(null);
 
-function App() {
-  return (
-    <ExodeUICanvas artboard={animationData} />
-  )
-}
+// ... inside your component
+<ExodeUICanvas 
+  src="/player_controller.json"
+  onReady={setEngine}
+/>
+
+// Button controls
+<button onClick={() => engine?.setInputBool('IsRunning', true)}>Run</button>
+<button onClick={() => engine?.fireTrigger('Jump')}>Jump</button>
 ```
 
-## API
+### 2. Physics Engine
+Built-in 2D physics using **Rapier**.
+- **Dynamic Bodies**: Objects that react to gravity and collisions.
+- **Static Bodies**: Platforms and walls.
+- **Kinematic**: Animated objects that push other bodies.
+- **Properties**: Mass, Friction, Restitution (Bounciness), Density.
 
-### `<ExodeUICanvas />`
+*Physics is configured directly in the ExodeUI Editor.*
+
+### 3. Data Visualization (Line Graphs)
+Render beautiful, animated line graphs with zero extra code.
+- **Line Graphs**: Supports multiple datasets, smoothing (Catmull-Rom splines), fill areas, and points.
+- **Data Binding**: Bind graph data to runtime inputs or variables.
+
+```tsx
+// Example of injecting data via Inputs (if supported by your graph configuration)
+// engine.setInputNumberArray('StockData', [10, 25, 15, 40, 35, 60]); 
+// (Note: array input support depends on your specific version/setup)
+```
+
+## API Reference
 
-The main component for rendering ExodeUI animations.
+### `<ExodeUICanvas />`
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `artboard` | `object` | `undefined` | The JSON animation data object. |
-| `src` | `string` | `undefined` | URL to fetch the animation JSON from. |
-| `autoPlay` | `boolean` | `true` | Whether the animation should start playing automatically. |
-| `fit` | `'Contain' \| 'Cover' \| 'Fill' \| 'FitWidth' \| 'FitHeight' \| 'None' \| 'ScaleDown'` | `'Contain'` | How the artboard fits within the canvas. |
-| `alignment` | `'Center' \| 'TopLeft' \| ...` | `'Center'` | How the content aligns if there is extra space. |
-| `onReady` | `(engine: ExodeUIEngine) => void` | `undefined` | Callback fired when the engine is loaded and ready. |
-| `style` | `CSSProperties` | `{ width: '100%', height: '100%' }` | CSS styles for the canvas element. |
-| `className` | `string` | `undefined` | CSS class name for the canvas element. |
+| `src` | `string` | - | URL to the animation JSON file. |
+| `artboard` | `object` | - | Direct JSON data object (if imported). |
+| `fit` | `'Contain' \| 'Cover' \| 'Fill'` | `'Contain'` | Scaling strategy. |
+| `alignment` | `'Center' \| 'TopLeft' ...` | `'Center'` | Alignment within the canvas. |
+| `autoPlay` | `boolean` | `true` | Auto-start the animation loop. |
+| `onReady` | `(engine: ExodeUIEngine) => void` | - | Callback when engine is initialized. |
+| `onTrigger` | `(name: string, animationName: string) => void` | - | Listener for outgoing triggers (events). |
+| `onInputUpdate` | `(nameOrId: string, value: any) => void` | - | Listener for input value changes. |
 
 ### `useExodeUI` Hook
 
-(Coming Soon)
-
-## State Machine Inputs
-
-You can control the animation state machine using the engine instance provided via `onReady`.
+A helper hook for easier engine management.
 
 ```tsx
-const [engine, setEngine] = useState<ExodeUIEngine | null>(null);
+import { useExodeUI, ExodeUICanvas } from 'exodeui';
 
-// ...
-
-<ExodeUICanvas 
-  artboard={data} 
-  onReady={(e) => {
-    setEngine(e);
-    
-    // Listen to triggers
-    e.setTriggerCallback((triggerName, animationName) => {
-      console.log(`Trigger "${triggerName}" fired! Playing "${animationName}"`);
-    });
-  }} 
-/>
+function Game() {
+  const { setEngine, setInputBool, fireTrigger } = useExodeUI();
 
-<button onClick={() => engine?.setInputBool('IsWalking', true)}>
-  Walk
-</button>
+  return (
+    <>
+      <ExodeUICanvas src="/game.json" onReady={setEngine} />
+      <div className="controls">
+          <button onMouseDown={() => setInputBool('Fire', true)}>Shoot</button>
+      </div>
+    </>
+  );
+}
 ```
 
-## Listening to Triggers
+## Advanced
 
-You can listen for interactive triggers (e.g. clicks on shapes) using `setTriggerCallback`:
+### Logic Nodes
+The engine automatically evaluates logic nodes defined in the editor.
+- **AND / OR / XOR / NOT** gates allow for complex condition evaluation without writing code.
+- Inputs are strictly typed: `Boolean`, `Number`, `Trigger` (momentary boolean), `Text`.
 
-```tsx
-<ExodeUICanvas 
-  artboard={data}
-  onReady={(engine) => {
-    engine.setTriggerCallback((triggerName, animationName) => {
-       // Handle side effects here (e.g. navigation, sound, analytics)
-       console.log(triggerName, animationName);
-    });
-  }}
-/>
-```
+### Custom Fonts
+Ensure any custom fonts used in the ExodeUI editor are loaded in your web page (e.g., via Google Fonts or `@font-face`) for correct rendering.
 
 ## License
 

package/dist/__tests__/comprehensiveArtboard.d.ts

@@ -0,0 +1,3 @@
+import { Artboard } from '../types';
+
+export declare const comprehensiveArtboard: Artboard;

package/dist/__tests__/engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine.d.ts

@@ -12,12 +12,15 @@ export declare class ExodeUIEngine {
     private layout;
     private onTrigger?;
     private onInputUpdate?;
+    private justFiredTriggers;
+    private lastHoveredObjectId;
     setTriggerCallback(cb: (triggerName: string, animationName: string) => void): void;
     setInputUpdateCallback(cb: (nameOrId: string, value: any) => void): void;
     constructor();
     private setInternalInput;
     setLayout(fit: Fit, alignment: Alignment): void;
     getActiveStateIds(layerName?: string): string[];
+    getObjectState(id: string): any;
     load(data: Artboard): void;
     reset(): void;
     private enterStates;
@@ -25,13 +28,26 @@ export declare class ExodeUIEngine {
     setInputNumber(nameOrId: string, value: number): void;
     fireTrigger(nameOrId: string): void;
     setInputText(nameOrId: string, value: string): void;
+    setInputNumberArray(nameOrId: string, value: number[]): void;
     private updateInput;
     private evaluateTransitions;
+    /**
+     * Find a global transition from any state in the layer whose conditions are met.
+     * This allows inputs to act as "global listeners" that can trigger state changes
+     * from any state, not just the current state.
+     *
+     * @param layer - The state machine layer to search
+     * @param currentStateIds - The currently active state IDs (to skip)
+     * @returns The first matching transition, or null if none found
+     */
+    private findGlobalTransition;
     private checkConditions;
+    private evaluateLogicTree;
     private activeTriggers;
     advance(dt: number): void;
     handlePointerInput(type: string, canvasX: number, canvasY: number, canvasWidth: number, canvasHeight: number): void;
     private handlePointerEvent;
+    private fireEventForObject;
     private hitTest;
     private applyAnimation;
     private interpolate;
@@ -39,4 +55,6 @@ export declare class ExodeUIEngine {
     render(ctx: CanvasRenderingContext2D, width: number, height: number): void;
     private calculateTransform;
     private renderObject;
+    private renderLineGraph;
+    private _catmullRom;
 }