canvasengine 2.0.0-beta.3 → 2.0.0-beta.5

package/index.d.ts

@@ -0,0 +1,4 @@
+declare module '*.ce' {
+    const content: import("./dist/index").ComponentFunction;
+    export default content;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvasengine",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/components/Graphic.ts

@@ -37,7 +37,7 @@ interface SvgProps extends DisplayObjectProps {
 }
 
 class CanvasGraphics extends DisplayObject(PixiGraphics) {
-  onInit(props: GraphicsProps) {
+  onInit(props) {
     super.onInit(props);
     if (props.draw) {
       effect(() => {

package/src/components/Sprite.ts

@@ -227,6 +227,24 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
   async onUpdate(props) {
     super.onUpdate(props);
 
+    const setTexture = async (image: string) => {
+      const onProgress = this.fullProps.loader?.onProgress;
+      const texture = await Assets.load(image, (progress) => {
+        if (onProgress) onProgress(progress);
+        if (progress == 1) {
+          const onComplete = this.fullProps.loader?.onComplete;
+          if (onComplete) {
+            // hack to memoize the texture
+            setTimeout(() => {
+              onComplete(texture);
+            });
+          }
+        }
+      });
+
+      return texture
+    }
+
     const sheet = props.sheet;
     if (sheet?.params) this.sheetParams = sheet?.params;
 
@@ -239,14 +257,13 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
 
     if (props.scaleMode) this.baseTexture.scaleMode = props.scaleMode;
     else if (props.image && this.fullProps.rectangle === undefined) {
-      this.texture = await Assets.load(this.fullProps.image);
+      this.texture = await setTexture(this.fullProps.image);
     } else if (props.texture) {
       this.texture = props.texture;
     }
-
     if (props.rectangle !== undefined) {
       const { x, y, width, height } = props.rectangle?.value ?? props.rectangle;
-      const texture = await Assets.load(this.fullProps.image);
+      const texture = await setTexture(this.fullProps.image);
       this.texture = new Texture({
         source: texture.source,
         frame: new Rectangle(x, y, width, height),
@@ -483,6 +500,10 @@ export interface SpritePropsWithSheet
     params?: any;
     onFinish?: () => void;
   };
+  loader?: {
+    onProgress?: (progress: number) => void;
+    onComplete?: (texture: Texture) => void;
+  };
 }
 
 export type SpritePropTypes = SpritePropsWithImage | SpritePropsWithSheet;

package/src/components/Video.ts

@@ -0,0 +1,110 @@
+import { Texture } from "pixi.js";
+import { h, mount } from "../engine/signal";
+import { useDefineProps } from "../hooks/useProps";
+import { Sprite } from "./Sprite";
+import { effect, Signal, signal } from "@signe/reactive";
+
+interface VideoProps {
+    source: string;
+    paused?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    loader?: {
+        onComplete?: (texture: Texture) => void;
+        onProgress?: (progress: number) => void;
+    };
+}
+
+export function Video(props: VideoProps) {
+    const eventsMap = {
+        audioprocess: null,
+        canplay: null,
+        canplaythrough: null,
+        complete: null,
+        durationchange: null,
+        emptied: null,
+        ended: null,
+        loadeddata: null,
+        loadedmetadata: null,
+        pause: null,
+        play: null,
+        playing: null,
+        progress: null,
+        ratechange: null,
+        seeked: null,
+        seeking: null,
+        stalled: null,
+        suspend: null,
+        timeupdate: null,
+        volumechange: null,
+        waiting: null
+    }
+
+    const video: Signal<HTMLVideoElement | null> = signal(null)
+    const defineProps = useDefineProps(props)
+    const { play, loop, muted } = defineProps({
+        play: {
+            type: Boolean,
+            default: true
+        },
+        loop: {
+            type: Boolean,
+            default: false
+        },
+        muted: {
+            type: Boolean,
+            default: false
+        }
+    })
+
+    effect(() => {
+        const _video = video()
+        const state = play()
+        if (_video && state !== undefined) {
+            if (state) {
+                _video.play()
+            } else {
+                _video.pause()
+            }
+        }
+        if (_video && loop()) {
+            _video.loop = loop()
+        }
+        if (_video && muted()) {
+            _video.muted = muted()
+        }
+    })
+
+    mount(() => {
+        return () => {
+            for (let event in eventsMap) {
+                if (eventsMap[event]) {
+                    video().removeEventListener(event, eventsMap[event])
+                }
+            }
+        }
+    })
+
+    return h(Sprite, {
+        ...props,
+        image: props.source,
+        loader: {
+            onComplete: (texture) => {
+                const source = texture.source.resource
+                video.set(source)
+                if (props?.loader?.onComplete) {
+                    props.loader.onComplete(texture)
+                }
+                for (let event in eventsMap) {
+                    if (props[event]) {
+                        const cb = (ev) => {
+                            props[event](ev)
+                        }
+                        eventsMap[event] = cb
+                        source.addEventListener(event, cb)
+                    }
+                }
+            }
+        }
+    })
+}

package/src/components/index.ts

@@ -4,6 +4,7 @@ export { Graphics, Rect, Circle, Ellipse, Triangle, Svg as svg } from './Graphic
 export { Scene } from './Scene'
 export { ParticlesEmitter } from './ParticleEmitter'
 export { Sprite } from './Sprite'
+export { Video } from './Video'
 export { Text } from './Text'
 export { TilingSprite } from './TilingSprite'
 export { Viewport } from './Viewport'

package/src/engine/reactive.ts

@@ -182,9 +182,24 @@ export function createComponent(tag: string, props?: Props): Element {
   }
 
   instance.onInit?.(element.props);
-  instance.onUpdate?.(element.props);
 
-  const onMount = (parent: Element, element: Element, index?: number) => {
+  const elementsListen = new Subject<any>()
+
+  if (props?.isRoot) {
+    element.allElements = elementsListen
+    element.props.context.rootElement = element;
+    element.componentInstance.onMount?.(element);
+    propagateContext(element);
+  }
+
+  if (props) {
+    for (let key in props) {
+      const directive = applyDirective(element, key);
+      if (directive) element.directives[key] = directive;
+    }
+  }
+
+  function onMount(parent: Element, element: Element, index?: number) {
     element.props.context = parent.props.context;
     element.parent = parent;
     element.componentInstance.onMount?.(element, index);
@@ -196,68 +211,79 @@ export function createComponent(tag: string, props?: Props): Element {
     });
   };
 
-  const elementsListen = new Subject<any>()
-
-  if (props?.isRoot) {
-    // propagate recrusively context in all children
-    const propagateContext = async (element) => {
-      if (!element.props.children) {
-        return;
+  async function propagateContext(element) {
+    if (element.props.attach) {
+      const isReactiveAttach = isSignal(element.propObservables?.attach)
+      if (!isReactiveAttach) {
+        element.props.children.push(element.props.attach)
       }
-      for (let child of element.props.children) {
-        if (!child) continue;
-        if (isPromise(child)) {
-          child = await child;
-        }
-        if (child instanceof Observable) {
-          child.subscribe(
-            ({
-              elements: comp,
-              prev,
-            }: {
-              elements: Element[];
-              prev?: Element;
-            }) => {
-              // if prev, insert element after this
-              const components = comp.filter((c) => c !== null);
-              if (prev) {
-                components.forEach((c) => {
-                  const index = element.props.children.indexOf(prev.props.key);
-                  onMount(element, c, index + 1);
-                  propagateContext(c);
-                });
-                return;
-              }
-              components.forEach((component) => {
-                if (!Array.isArray(component)) {
-                  onMount(element, component);
-                  propagateContext(component);
-                } else {
-                  component.forEach((comp) => {
-                    onMount(element, comp);
-                    propagateContext(comp);
-                  });
+      else {
+        await new Promise((resolve) => {
+            let lastElement = null
+            element.propSubscriptions.push(element.propObservables.attach.observable.subscribe(async (args) => {
+                const value = args?.value ?? args
+                if (!value) {
+                  throw new Error(`attach in ${element.tag} is undefined or null, add a component`)
                 }
+                if (lastElement) {
+                  destroyElement(lastElement)
+                }
+                lastElement = value
+                await createElement(element, value)
+                resolve(undefined)
+            }))
+        })
+      }
+    }
+    if (!element.props.children) {
+      return;
+    }
+    for (let child of element.props.children) {
+      if (!child) continue;
+      await createElement(element, child)
+    }
+  };
+
+  async function createElement(parent: Element, child: Element) {
+    if (isPromise(child)) {
+      child = await child;
+    }
+    if (child instanceof Observable) {
+      child.subscribe(
+        ({
+          elements: comp,
+          prev,
+        }: {
+          elements: Element[];
+          prev?: Element;
+        }) => {
+          // if prev, insert element after this
+          const components = comp.filter((c) => c !== null);
+          if (prev) {
+            components.forEach((c) => {
+              const index = parent.props.children.indexOf(prev.props.key);
+              onMount(parent, c, index + 1);
+              propagateContext(c);
+            });
+            return;
+          }
+          components.forEach((component) => {
+            if (!Array.isArray(component)) {
+              onMount(parent, component);
+              propagateContext(component);
+            } else {
+              component.forEach((comp) => {
+                onMount(parent, comp);
+                propagateContext(comp);
               });
-              elementsListen.next(undefined)
             }
-          );
-        } else {
-          onMount(element, child);
-          await propagateContext(child);
+          });
+          elementsListen.next(undefined)
         }
-      }
-    };
-    element.allElements = elementsListen
-    element.props.context.rootElement = element;
-    element.componentInstance.onMount?.(element);
-    propagateContext(element);
-  }
-
-  if (props) {
-    for (let key in props) {
-      const directive = applyDirective(element, key);
-      if (directive) element.directives[key] = directive;
+      );
+    } else {
+      onMount(parent, child);
+      await propagateContext(child);
     }
   }
 

package/src/engine/trigger.ts

@@ -2,39 +2,95 @@ import { effect, signal } from "@signe/reactive";
 
 interface Listen<T = any> {
   config: T | undefined;
-  seed: number;
+  seed: {
+    config: T | undefined;
+    value: number;
+    resolve: (value: any) => void;
+  };
 }
 
 interface Trigger<T = any> {
-  start: () => void;
+  start: () => Promise<void>;
   listen: () => Listen<T> | undefined;
 }
 
+/**
+ * Checks if the given argument is a Trigger object
+ * @param arg - The value to check
+ * @returns True if the argument is a Trigger object
+ */
 export function isTrigger(arg: any): arg is Trigger<any> {
   return arg?.start && arg?.listen;
 }
 
-export function trigger<T = any>(config?: T): Trigger<T> {
-  const _signal = signal(0);
+/**
+ * Creates a new trigger that can be used to pass data between components
+ * @param globalConfig - Optional configuration data to be passed when the trigger is activated
+ * @returns A Trigger object with start and listen methods
+ * @example
+ * ```ts
+ * const myTrigger = trigger()
+ * 
+ * on(myTrigger, (data) => {
+ *   console.log('Triggered with data:', data)
+ * })
+ * 
+ * myTrigger.start({ message: 'Hello' })
+ * ```
+ */
+export function trigger<T = any>(globalConfig?: T): Trigger<T> {
+  const _signal = signal({
+    config: globalConfig,
+    value: 0,
+    resolve: (value: any) => void 0,
+  });
   return {
-    start: () => {
-      _signal.set(Math.random());
+    start: (config?: T) => {
+      return new Promise((resolve: (value: any) => void) => {
+        _signal.set({
+          config: {
+            ...globalConfig,
+            ...config,
+          },
+          resolve,
+          value: Math.random(),
+        });
+      });
     },
     listen: (): Listen<T> | undefined => {
       return {
-        config,
+        config: globalConfig,
         seed: _signal(),
       };
     },
   };
 }
 
-export function on(triggerSignal: any, callback: (config: any) => void) {
+/**
+ * Subscribes to a trigger and executes a callback when the trigger is activated
+ * @param triggerSignal - The trigger to subscribe to
+ * @param callback - Function to execute when the trigger is activated
+ * @throws Error if triggerSignal is not a valid trigger
+ * @example
+ * ```ts
+ * const click = trigger()
+ * 
+ * on(click, () => {
+ *   console.log('Click triggered')
+ * })
+ * ```
+ */
+export function on(triggerSignal: any, callback: (config: any) => void | Promise<void>) {
   if (!isTrigger(triggerSignal)) {
     throw new Error("In 'on(arg)' must have a trigger signal type");
   }
   effect(() => {
     const result = triggerSignal.listen();
-    if (result?.seed) callback(result.config);
+    if (result?.seed.value) {
+      const ret = callback(result?.seed.config);
+      if (ret && typeof ret.then === 'function') {
+        ret.then(result?.seed.resolve);
+      }
+    }
   });
 }

package/src/engine/utils.ts

@@ -1,17 +1,35 @@
 import { ObservablePoint } from "pixi.js"
 
+/**
+ * Checks if code is running in a browser environment
+ * @returns {boolean} True if running in browser, false otherwise
+ */
 export function isBrowser(): boolean {
     return typeof window !== 'undefined'
 }
 
+/**
+ * Returns current high-resolution timestamp
+ * @returns {number} Current time in milliseconds
+ */
 export function preciseNow(): number {
     return typeof performance !== 'undefined' ? performance.now() : Date.now()
 }
 
+/**
+ * Converts frames per second to milliseconds
+ * @param {number} fps - Frames per second
+ * @returns {number} Milliseconds per frame
+ */
 export function fps2ms(fps: number): number {
     return 1000 / fps
 }
 
+/**
+ * Checks if a value is a Promise
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a Promise, false otherwise
+ */
 export function isPromise(value: any): boolean {
     return value && value instanceof Promise
 }
@@ -58,15 +76,38 @@ function deepEquals(a: any, b: any): boolean {
     return false;
 }
 
+/**
+ * Checks if a value is a function
+ * @param {unknown} val - Value to check
+ * @returns {boolean} True if value is a function, false otherwise
+ */
 export function isFunction(val: unknown): boolean {
     return {}.toString.call(val) === '[object Function]'
 }
 
+/**
+ * Checks if a value is a plain object
+ * @param {unknown} val - Value to check
+ * @returns {boolean} True if value is an object (not null and not array), false otherwise
+ */
 export function isObject(val: unknown): boolean {
     return typeof val == 'object' && val != null && !Array.isArray(val)
 }
 
-export function set(obj, path, value, onlyPlainObject = false) {
+/**
+ * Sets a value in an object using a dot notation path
+ * @param {Record<string, any>} obj - Target object
+ * @param {string | string[]} path - Path to set value at (e.g., 'a.b.c' or ['a', 'b', 'c'])
+ * @param {any} value - Value to set
+ * @param {boolean} onlyPlainObject - If true, only creates plain objects in path
+ * @returns {Record<string, any>} Modified object
+ */
+export function set(
+    obj: Record<string, any>, 
+    path: string | string[], 
+    value: any, 
+    onlyPlainObject = false
+): Record<string, any> {
     if (Object(obj) !== obj) return obj;
 
     if (typeof path === 'string') {
@@ -79,8 +120,8 @@ export function set(obj, path, value, onlyPlainObject = false) {
     let current = obj;
     for (let i = 0; i < len - 1; i++) {
         let segment = path[i];
-        let nextSegment = path[i + 1];
-        let isNextNumeric = !isNaN(nextSegment) && isFinite(nextSegment);
+        let nextSegment: number | string = path[i + 1];
+        let isNextNumeric = !isNaN(Number(nextSegment)) && isFinite(Number(nextSegment));
 
         if (!current[segment] || typeof current[segment] !== 'object') {
             current[segment] = (isNextNumeric && !onlyPlainObject) ? [] : {};
@@ -94,7 +135,13 @@ export function set(obj, path, value, onlyPlainObject = false) {
     return obj;
 }
 
-export function get(obj, path) {
+/**
+ * Gets a value from an object using a dot notation path
+ * @param {Record<string, any>} obj - Source object
+ * @param {string} path - Path to get value from (e.g., 'a.b.c')
+ * @returns {any} Value at path or undefined if not found
+ */
+export function get(obj: Record<string, any>, path: string): any {
     const keys = path.split('.');
     let current = obj;
 
@@ -108,15 +155,31 @@ export function get(obj, path) {
     return current;
 }
 
-export function log(text) {
+/**
+ * Logs a message to console
+ * @param {any} text - Message to log
+ */
+export function log(text: any): void {
     console.log(text)
 }
 
-export function error(text) {
+/**
+ * Logs an error message to console
+ * @param {any} text - Error message to log
+ */
+export function error(text: any): void {
     console.error(text)
 }
 
-export function setObservablePoint(observablePoint: ObservablePoint, point: { x: number, y: number } | number | [number, number]): void {
+/**
+ * Sets the position of an ObservablePoint using various input formats
+ * @param {ObservablePoint} observablePoint - The point to modify
+ * @param {Object | number | [number, number]} point - New position value
+ */
+export function setObservablePoint(
+    observablePoint: ObservablePoint, 
+    point: { x: number, y: number } | number | [number, number]
+): void {
     if (typeof point === 'number') {
         observablePoint.set(point);
     }
@@ -128,7 +191,20 @@ export function setObservablePoint(observablePoint: ObservablePoint, point: { x:
     }
 }
 
-export function calculateDistance(x1, y1, x2, y2) {
+/**
+ * Calculates the Euclidean distance between two points
+ * @param {number} x1 - X coordinate of first point
+ * @param {number} y1 - Y coordinate of first point
+ * @param {number} x2 - X coordinate of second point
+ * @param {number} y2 - Y coordinate of second point
+ * @returns {number} Distance between the points
+ */
+export function calculateDistance(
+    x1: number, 
+    y1: number, 
+    x2: number, 
+    y2: number
+): number {
     const dx = x1 - x2;
     const dy = y1 - y2;
     return Math.sqrt(dx * dx + dy * dy);

package/src/index.ts

@@ -11,4 +11,5 @@ export { useProps, useDefineProps } from './hooks/useProps'
 export * from './utils/Ease'
 export * from './utils/RadialGradient'
 export * from './components/DisplayObject'
-export { isObservable } from 'rxjs'
+export { isObservable } from 'rxjs'
+export * as Utils from './engine/utils'

package/src/utils/RadialGradient.ts

@@ -1,5 +1,13 @@
 import { Texture, ImageSource, DOMAdapter, Matrix } from "pixi.js";
 
+/**
+ * Creates a radial gradient texture that can be used in PixiJS.
+ * @example
+ * const gradient = new RadialGradient(size, size, 0, size, size, 0);
+ * gradient.addColorStop(0, "rgba(255, 255, 0, 1)");
+ * gradient.addColorStop(0.5, "rgba(255, 255, 0, 0.3)");
+ * gradient.addColorStop(0.8, "rgba(255, 255, 0, 0)");
+ */
 export class RadialGradient {
   private canvas: HTMLCanvasElement;
   private ctx: CanvasRenderingContext2D | null;
@@ -9,6 +17,16 @@ export class RadialGradient {
 
   public size = 600;
 
+  /**
+   * Creates a new RadialGradient instance
+   * @param x0 - The x-coordinate of the starting circle
+   * @param y0 - The y-coordinate of the starting circle
+   * @param x1 - The x-coordinate of the ending circle
+   * @param y1 - The y-coordinate of the ending circle
+   * @param x2 - The x-coordinate for gradient transformation
+   * @param y2 - The y-coordinate for gradient transformation
+   * @param focalPoint - The focal point of the gradient (0-1), defaults to 0
+   */
   constructor(
     private x0: number,
     private y0: number,
@@ -38,12 +56,23 @@ export class RadialGradient {
     }
   }
 
+  /**
+   * Adds a color stop to the gradient
+   * @param offset - The position of the color stop (0-1)
+   * @param color - The color value (any valid CSS color string)
+   */
   addColorStop(offset: number, color: string) {
     if (this.gradient) {
       this.gradient.addColorStop(offset, color);
     }
   }
 
+  /**
+   * Renders the gradient and returns the texture with its transformation matrix
+   * @param options - Render options
+   * @param options.translate - Optional translation coordinates
+   * @returns Object containing the texture and transformation matrix
+   */
   render({ translate }: { translate?: { x: number; y: number } } = {}) {
     const { x0, y0, x1, y1, x2, y2, focalPoint } = this;
     const defaultSize = this.size;