canvasengine 2.0.1-beta.2 → 2.0.1

package/src/engine/utils.ts

@@ -1,17 +1,37 @@
+import { isSignal } from "@signe/reactive"
 import { ObservablePoint } from "pixi.js"
+import { Observable } from "rxjs"
 
+/**
+ * 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 +78,49 @@ 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 (not an instance of a class)
+ * @param {unknown} val - Value to check
+ * @returns {boolean} True if value is a plain object (not null, not array, not instance), false otherwise
+ * @example
+ * ```ts
+ * isObject({}) // true
+ * isObject(new Date()) // false
+ * isObject([]) // false
+ * isObject(null) // false
+ * ```
+ */
 export function isObject(val: unknown): boolean {
-    return typeof val == 'object' && val != null && !Array.isArray(val)
+    return typeof val == 'object' && val != null && !Array.isArray(val) && val.constructor === Object
 }
 
-export function set(obj, path, value, onlyPlainObject = false) {
+export function isObservable(val: unknown): boolean {
+    return val instanceof Observable
+}
+
+/**
+ * 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 +133,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 +148,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,27 +168,59 @@ 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);
     }
     else if (Array.isArray(point)) {
         observablePoint.set(point[0], point[1]);
     }
+    else if (isObject(point) && 'value' in point) {
+        observablePoint.set((point as any).value.x, (point as any).value.y);
+    }
     else {
         observablePoint.set(point.x, point.y);
     }
 }
 
-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/hooks/useFocus.ts

@@ -0,0 +1,91 @@
+import { Signal } from "@signe/reactive";
+import { Element } from "../engine/reactive";
+import { focusManager } from "../engine/FocusManager";
+import { effect } from "@signe/reactive";
+
+/**
+ * Get the current focus index signal for a container
+ * 
+ * Returns a reactive signal that updates when the focus index changes.
+ * 
+ * @param containerId - Container identifier
+ * @returns Signal for current focus index, or null if container not found
+ * 
+ * @example
+ * ```typescript
+ * const focusIndex = useFocusIndex('myContainer');
+ * effect(() => {
+ *   console.log('Current focus index:', focusIndex?.());
+ * });
+ * ```
+ */
+export function useFocusIndex(containerId: string): Signal<number | null> | null {
+  return focusManager.getCurrentIndexSignal(containerId);
+}
+
+/**
+ * Get the current focused element signal for a container
+ * 
+ * Returns a reactive signal that updates when the focused element changes.
+ * 
+ * @param containerId - Container identifier
+ * @returns Signal for current focused element, or null if container not found
+ * 
+ * @example
+ * ```typescript
+ * const focusedElement = useFocusedElement('myContainer');
+ * effect(() => {
+ *   const element = focusedElement?.();
+ *   if (element) {
+ *     console.log('Focused element:', element);
+ *   }
+ * });
+ * ```
+ */
+export function useFocusedElement(containerId: string): Signal<Element | null> | null {
+  return focusManager.getFocusedElementSignal(containerId);
+}
+
+/**
+ * Hook to react to focus changes
+ * 
+ * Sets up a reactive effect that calls the callback whenever the focus changes.
+ * 
+ * @param containerId - Container identifier
+ * @param callback - Function to call when focus changes
+ * @returns Cleanup function to unsubscribe
+ * 
+ * @example
+ * ```typescript
+ * useFocusChange('myContainer', (index, element) => {
+ *   console.log('Focus changed to index', index);
+ *   if (element) {
+ *     console.log('Focused element:', element);
+ *   }
+ * });
+ * ```
+ */
+export function useFocusChange(
+  containerId: string,
+  callback: (index: number | null, element: Element | null) => void
+): () => void {
+  const indexSignal = focusManager.getCurrentIndexSignal(containerId);
+  const elementSignal = focusManager.getFocusedElementSignal(containerId);
+
+  if (!indexSignal || !elementSignal) {
+    console.warn(`FocusContainer with id "${containerId}" not found`);
+    return () => {};
+  }
+
+  // Set up reactive effect
+  const effectResult = effect(() => {
+    const index = indexSignal();
+    const element = elementSignal();
+    callback(index, element);
+  });
+
+  // Return cleanup function
+  return () => {
+    effectResult.subscription?.unsubscribe();
+  };
+}

package/src/hooks/useProps.ts

@@ -1,5 +1,7 @@
 import { isSignal, signal } from "@signe/reactive"
 import { isPrimitive } from "../engine/reactive"
+import { currentDefinePropsTracker } from "../engine/signal"
+import { isTrigger } from "../engine/trigger"
 
 /**
  * Converts props into reactive signals if they are primitive values.
@@ -25,7 +27,7 @@ export const useProps = (props, defaults = {}): any => {
     }
     for (let key in defaults) {
         if (!(key in obj)) {
-            obj[key] = signal(defaults[key])
+            obj[key] = isPrimitive(defaults[key]) ? signal(defaults[key]) : defaults[key]
         }
     }
     return obj
@@ -46,6 +48,45 @@ type PropSchema = {
     [key: string]: PropType | PropType[] | PropConfig;
 }
 
+const DEFINE_PROPS_CALLABLE_SIGNAL_VALUE = "__canvasEngineCallableSignalValue"
+
+const createCallablePropSignal = (value: (...args: any[]) => any) => {
+    const valueSignal: any = signal(value)
+    const callable: any = (...args: any[]) => valueSignal()(...args)
+
+    callable[DEFINE_PROPS_CALLABLE_SIGNAL_VALUE] = valueSignal
+    callable.set = valueSignal.set
+    callable.freeze = valueSignal.freeze
+    callable.unfreeze = valueSignal.unfreeze
+    callable.mutate = valueSignal.mutate
+    callable.update = valueSignal.update
+    callable.observable = valueSignal.observable
+    callable._subject = valueSignal._subject
+
+    Object.defineProperty(callable, "_isFrozen", {
+        get: () => valueSignal._isFrozen,
+        set: (value) => {
+            valueSignal._isFrozen = value
+        }
+    })
+
+    return callable
+}
+
+const toPropSignal = (value: any) => {
+    if (isSignal(value) || isTrigger(value)) return value
+    if (typeof value === 'function') return createCallablePropSignal(value)
+    return signal(value)
+}
+
+const definePropSignals = (props: any): any => {
+    const obj: any = {}
+    for (let key in props) {
+        obj[key] = toPropSignal(props[key])
+    }
+    return obj
+}
+
 /**
  * Validates and defines properties based on a schema.
  * 
@@ -109,18 +150,62 @@ export const useDefineProps = (props: any) => {
                 }
             }
 
-            validatedProps[key] = isSignal(validatedValue) 
-                ? validatedValue 
-                : signal(validatedValue)
+            validatedProps[key] = toPropSignal(validatedValue)
         }
         
-        return {
-            ...useProps(rawProps),
+        const definedProps = {
+            ...definePropSignals(rawProps),
             ...validatedProps
         }
+        currentDefinePropsTracker?.(definedProps)
+
+        return definedProps
     }
 }
 
+const getRawProps = (props: any) => isSignal(props) ? props() : (props ?? {})
+
+const getEmitHandler = (handler: any) => {
+    if (handler?.[DEFINE_PROPS_CALLABLE_SIGNAL_VALUE]) return handler
+    if (isSignal(handler)) return handler()
+    return handler
+}
+
+/**
+ * Defines event emitters from component props.
+ *
+ * @param {object} props - The raw component props containing event handlers.
+ * @returns {function} A function returning named emit callbacks.
+ *
+ * @example
+ * const { select } = useDefineEmits({ select: (item) => item.id })();
+ * select({ id: 1 });
+ */
+export const useDefineEmits = (props: any) => {
+    return () => new Proxy({}, {
+        get(_target, key) {
+            if (typeof key !== 'string') {
+                return undefined
+            }
+
+            return (...args: any[]) => {
+                const rawProps = getRawProps(props)
+                const handler = getEmitHandler(rawProps[key])
+
+                if (handler === undefined || handler === null) {
+                    return undefined
+                }
+
+                if (typeof handler !== 'function') {
+                    throw new Error(`Invalid emit handler: "${key}" must be a function`)
+                }
+
+                return handler(...args)
+            }
+        }
+    })
+}
+
 /**
  * Validates the type of a property.
  * 
@@ -152,4 +237,4 @@ function validateType(key: string, value: any, types: any[]) {
             `Expected ${types.map(t => t.name).join(' or ')}`
         )
     }
-}
+}

package/src/index.ts

@@ -1,14 +1,21 @@
-import './directives'
+
+export * from './directives'
 export * from '@signe/reactive'
 export { Howler } from 'howler'
 export * from './components'
 export * from './engine/reactive'
+export { registerAllComponents } from './engine/reactive'
 export * from './engine/signal'
 export * from './engine/trigger'
 export * from './engine/bootstrap'
 export * from './engine/animation'
-export { useProps, useDefineProps } from './hooks/useProps'
-
-export * from './presets/Bar'
-export * from './presets/Particle'
-export * from './utils/Ease'
+export { FocusManager, focusManager, type ScrollOptions } from './engine/FocusManager'
+export { useProps, useDefineProps, useDefineEmits } from './hooks/useProps'
+export { useFocusIndex, useFocusedElement, useFocusChange } from './hooks/useFocus'
+export * from './utils/Ease'
+export * from './utils/RadialGradient'
+export * from './utils/tabindex'
+export * from './components/DisplayObject'
+export { isObservable } from 'rxjs'
+export * as Utils from './engine/utils'
+export * as Howl from 'howler'

package/src/types/pixi-cull.d.ts

@@ -0,0 +1,7 @@
+declare module "pixi-cull" {
+  export class Simple {
+    constructor(options?: any);
+    lists: Array<any>;
+    cull(bounds: any): void;
+  }
+}

package/src/utils/GlobalAssetLoader.ts

@@ -0,0 +1,257 @@
+/**
+ * Global Asset Loader
+ * 
+ * Tracks the loading progress of all assets (images, spritesheets, etc.) across all sprites in a component tree.
+ * This allows components to know when all assets are loaded, useful for displaying loaders or progress bars.
+ * 
+ * @example
+ * ```typescript
+ * const loader = new GlobalAssetLoader();
+ * 
+ * loader.onProgress((progress) => {
+ *   console.log(`Loading: ${(progress * 100).toFixed(0)}%`);
+ * });
+ * 
+ * loader.onComplete(() => {
+ *   console.log('All assets loaded!');
+ * });
+ * 
+ * // Register assets as they start loading
+ * const assetId = loader.registerAsset('path/to/image.png');
+ * 
+ * // Update progress
+ * loader.updateProgress(assetId, 0.5);
+ * 
+ * // Mark as complete
+ * loader.completeAsset(assetId);
+ * ```
+ */
+export class GlobalAssetLoader {
+  private assets: Map<string, { progress: number; completed: boolean }> = new Map();
+  private onProgressCallbacks: Set<(progress: number) => void> = new Set();
+  private onCompleteCallbacks: Set<() => void> = new Set();
+  private assetCounter: number = 0;
+  private isComplete: boolean = false;
+
+  /**
+   * Registers a new asset to track
+   * 
+   * @param assetPath - The path or identifier of the asset being loaded
+   * @returns A unique ID for this asset that should be used for progress updates
+   * 
+   * @example
+   * ```typescript
+   * const assetId = loader.registerAsset('path/to/image.png');
+   * ```
+   */
+  registerAsset(assetPath: string): string {
+    const assetId = `asset_${this.assetCounter++}_${assetPath}`;
+    this.assets.set(assetId, { progress: 0, completed: false });
+    this.isComplete = false;
+    this.updateGlobalProgress();
+    return assetId;
+  }
+
+  /**
+   * Updates the progress of a specific asset
+   * 
+   * @param assetId - The ID returned by registerAsset
+   * @param progress - Progress value between 0 and 1
+   * 
+   * @example
+   * ```typescript
+   * loader.updateProgress(assetId, 0.5); // 50% loaded
+   * ```
+   */
+  updateProgress(assetId: string, progress: number): void {
+    const asset = this.assets.get(assetId);
+    if (!asset) {
+      console.warn(`Asset ${assetId} not found in tracker`);
+      return;
+    }
+    
+    asset.progress = Math.max(0, Math.min(1, progress));
+    this.updateGlobalProgress();
+  }
+
+  /**
+   * Marks an asset as completely loaded
+   * 
+   * @param assetId - The ID returned by registerAsset
+   * 
+   * @example
+   * ```typescript
+   * loader.completeAsset(assetId);
+   * ```
+   */
+  completeAsset(assetId: string): void {
+    const asset = this.assets.get(assetId);
+    if (!asset) {
+      console.warn(`Asset ${assetId} not found in tracker`);
+      return;
+    }
+    
+    asset.progress = 1;
+    asset.completed = true;
+    this.updateGlobalProgress();
+    this.checkCompletion();
+  }
+
+  /**
+   * Removes an asset from tracking (useful for cleanup)
+   * 
+   * @param assetId - The ID returned by registerAsset
+   */
+  removeAsset(assetId: string): void {
+    this.assets.delete(assetId);
+    this.updateGlobalProgress();
+  }
+
+  /**
+   * Registers a callback that will be called whenever the global progress changes
+   * 
+   * @param callback - Function that receives the global progress (0-1)
+   * @returns A function to unregister the callback
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = loader.onProgress((progress) => {
+   *   console.log(`Loading: ${(progress * 100).toFixed(0)}%`);
+   * });
+   * 
+   * // Later, to unsubscribe:
+   * unsubscribe();
+   * ```
+   */
+  onProgress(callback: (progress: number) => void): () => void {
+    this.onProgressCallbacks.add(callback);
+    
+    // Immediately call with current progress (wrap in try-catch for safety)
+    try {
+      callback(this.getGlobalProgress());
+    } catch (error) {
+      console.error('Error in onProgress callback:', error);
+    }
+    
+    return () => {
+      this.onProgressCallbacks.delete(callback);
+    };
+  }
+
+  /**
+   * Registers a callback that will be called when all assets are loaded
+   * 
+   * @param callback - Function to call when all assets are complete
+   * @returns A function to unregister the callback
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = loader.onComplete(() => {
+   *   console.log('All assets loaded!');
+   * });
+   * 
+   * // Later, to unsubscribe:
+   * unsubscribe();
+   * ```
+   */
+  onComplete(callback: () => void): () => void {
+    this.onCompleteCallbacks.add(callback);
+    
+    // If already complete, call immediately
+    if (this.isComplete) {
+      callback();
+    }
+    
+    return () => {
+      this.onCompleteCallbacks.delete(callback);
+    };
+  }
+
+  /**
+   * Gets the current global progress (0-1)
+   * 
+   * @returns Progress value between 0 and 1
+   */
+  getGlobalProgress(): number {
+    if (this.assets.size === 0) {
+      return 1; // No assets means everything is "loaded"
+    }
+    
+    let totalProgress = 0;
+    for (const asset of this.assets.values()) {
+      totalProgress += asset.progress;
+    }
+    
+    return totalProgress / this.assets.size;
+  }
+
+  /**
+   * Gets the number of assets currently being tracked
+   * 
+   * @returns Number of registered assets
+   */
+  getAssetCount(): number {
+    return this.assets.size;
+  }
+
+  /**
+   * Gets the number of completed assets
+   * 
+   * @returns Number of completed assets
+   */
+  getCompletedCount(): number {
+    let count = 0;
+    for (const asset of this.assets.values()) {
+      if (asset.completed) count++;
+    }
+    return count;
+  }
+
+  /**
+   * Checks if all assets are loaded and triggers onComplete callbacks
+   */
+  private checkCompletion(): void {
+    if (this.isComplete) return;
+    
+    const allCompleted = Array.from(this.assets.values()).every(asset => asset.completed);
+    
+    if (allCompleted && this.assets.size > 0) {
+      this.isComplete = true;
+      this.onCompleteCallbacks.forEach(callback => {
+        try {
+          callback();
+        } catch (error) {
+          console.error('Error in onComplete callback:', error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Updates global progress and notifies all progress callbacks
+   */
+  private updateGlobalProgress(): void {
+    const progress = this.getGlobalProgress();
+    // Create a copy of callbacks to avoid issues if callbacks modify the set
+    const callbacks = Array.from(this.onProgressCallbacks);
+    callbacks.forEach(callback => {
+      try {
+        callback(progress);
+      } catch (error) {
+        console.error('Error in onProgress callback:', error);
+      }
+    });
+  }
+
+  /**
+   * Resets the loader, clearing all assets and callbacks
+   */
+  reset(): void {
+    this.assets.clear();
+    this.onProgressCallbacks.clear();
+    this.onCompleteCallbacks.clear();
+    this.assetCounter = 0;
+    this.isComplete = false;
+  }
+}
+