@grandgular/rive-angular 0.3.0 → 0.4.0

package/types/grandgular-rive-angular.d.ts

@@ -1,7 +1,44 @@
 import * as _angular_core from '@angular/core';
 import { AfterViewInit, Signal, Provider } from '@angular/core';
-import { RiveFile, Fit, Alignment, Event, Rive } from '@rive-app/canvas';
-export { Alignment, EventType, Fit, Layout, LayoutParameters, Rive, Event as RiveEvent, RiveFile, RiveFileParameters, RiveParameters, StateMachineInput } from '@rive-app/canvas';
+import { RiveFile, Fit, Alignment, Event, Rive, ViewModelInstance } from '@rive-app/canvas';
+export { Alignment, EventType, Fit, Layout, LayoutParameters, Rive, Event as RiveEvent, RiveFile, RiveFileParameters, RiveParameters, StateMachineInput, ViewModelInstance } from '@rive-app/canvas';
+
+/**
+ * Represents a color value in RGBA format for Rive animations.
+ * All components are in the range 0-255.
+ */
+interface RiveColor {
+    /** Red component (0-255) */
+    r: number;
+    /** Green component (0-255) */
+    g: number;
+    /** Blue component (0-255) */
+    b: number;
+    /** Alpha component (0-255), defaults to 255 (fully opaque) */
+    a: number;
+}
+/**
+ * Union type representing all possible data binding values.
+ * Used in the dataBindings input to support multiple property types.
+ */
+type DataBindingValue = number | string | boolean | RiveColor;
+/**
+ * Enum representing the type of a ViewModel property.
+ * Used for type detection and validation.
+ */
+type DataBindingPropertyType = 'number' | 'string' | 'boolean' | 'color' | 'enum' | 'trigger';
+/**
+ * Event emitted when a ViewModel property changes from within the animation.
+ * This enables two-way data binding between the animation and Angular application.
+ */
+interface DataBindingChangeEvent {
+    /** Path to the property in the ViewModel */
+    path: string;
+    /** New value of the property */
+    value: DataBindingValue;
+    /** Type of the property that changed */
+    propertyType: DataBindingPropertyType;
+}
 
 /**
  * Standalone Angular component for Rive animations
@@ -73,6 +110,30 @@ declare class RiveCanvasComponent implements AfterViewInit {
      * Values are applied reactively when input changes.
      */
     readonly textRuns: _angular_core.InputSignal<Record<string, string> | undefined>;
+    /**
+     * Name of the ViewModel to use for data binding.
+     * If not provided, uses the default ViewModel for the artboard.
+     * Only relevant if the .riv file contains ViewModels.
+     */
+    readonly viewModelName: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Record of ViewModel property paths to values for declarative data binding.
+     * Keys present in this input are CONTROLLED — the input is the source of truth.
+     * Keys absent from this input are UNCONTROLLED — managed imperatively.
+     * Values are applied reactively when input changes.
+     *
+     * Supports multiple data types: number, string, boolean, RiveColor.
+     * The component auto-detects the property type from the ViewModel.
+     *
+     * @example
+     * [dataBindings]="{
+     *   backgroundColor: '#FF5733',
+     *   score: 42,
+     *   playerName: 'Alice',
+     *   isActive: true
+     * }"
+     */
+    readonly dataBindings: _angular_core.InputSignal<Record<string, DataBindingValue> | undefined>;
     readonly loaded: _angular_core.OutputEmitterRef<void>;
     readonly loadError: _angular_core.OutputEmitterRef<Error>;
     /**
@@ -91,6 +152,12 @@ declare class RiveCanvasComponent implements AfterViewInit {
      * Note: This fires AFTER the animation is loaded, not just instantiated.
      */
     readonly riveReady: _angular_core.OutputEmitterRef<Rive>;
+    /**
+     * Emitted when a ViewModel property changes from within the animation.
+     * Enables two-way data binding between the animation and Angular application.
+     * Only fires if the .riv file uses ViewModels with callbacks.
+     */
+    readonly dataBindingChange: _angular_core.OutputEmitterRef<DataBindingChangeEvent>;
     readonly isPlaying: _angular_core.Signal<boolean>;
     readonly isPaused: _angular_core.Signal<boolean>;
     readonly isLoaded: _angular_core.Signal<boolean>;
@@ -99,6 +166,12 @@ declare class RiveCanvasComponent implements AfterViewInit {
      * Use this to access advanced Rive SDK features.
      */
     readonly riveInstance: _angular_core.Signal<Rive | null>;
+    /**
+     * Public signal providing access to the ViewModel instance.
+     * Use this to access advanced ViewModel features for data binding.
+     * Returns null if the .riv file doesn't use ViewModels.
+     */
+    readonly viewModelInstance: _angular_core.Signal<ViewModelInstance | null>;
     private readonly logger;
     private resizeObserver;
     private isInitialized;
@@ -185,17 +258,102 @@ declare class RiveCanvasComponent implements AfterViewInit {
      * Note: AtPath text runs are always uncontrolled (not managed by textRuns input).
      */
     setTextRunValueAtPath(textRunName: string, textRunValue: string, path: string): void;
+    /**
+     * Set a data binding value in the ViewModel.
+     * Auto-detects the property type and applies the value accordingly.
+     * Warning: If the property is controlled by dataBindings input, this change
+     * will be overwritten on the next input update.
+     */
+    setDataBinding(path: string, value: DataBindingValue): void;
+    /**
+     * Get a data binding value from the ViewModel.
+     * Auto-detects the property type and returns the value accordingly.
+     * Returns undefined if the property doesn't exist or ViewModel is not loaded.
+     */
+    getDataBinding(path: string): DataBindingValue | undefined;
+    /**
+     * Fire a trigger property in the ViewModel.
+     * Use this for ViewModel-based triggers (data binding).
+     * For state machine triggers, use fireTrigger(stateMachineName, triggerName).
+     */
+    fireViewModelTrigger(path: string): void;
+    /**
+     * Set a color value in the ViewModel.
+     * Accepts hex string ('#RRGGBB' or '#RRGGBBAA'), ARGB integer, or RiveColor object.
+     * Warning: If the property is controlled by dataBindings input, this change
+     * will be overwritten on the next input update.
+     */
+    setColor(path: string, color: string | number | RiveColor): void;
+    /**
+     * Get a color value from the ViewModel.
+     * Returns undefined if the property doesn't exist or ViewModel is not loaded.
+     */
+    getColor(path: string): RiveColor | undefined;
+    /**
+     * Set a color value using RGBA components (0-255).
+     * Warning: If the property is controlled by dataBindings input, this change
+     * will be overwritten on the next input update.
+     */
+    setColorRgba(path: string, r: number, g: number, b: number, a?: number): void;
+    /**
+     * Set the opacity of a color (0.0-1.0) while preserving RGB values.
+     * Warning: If the property is controlled by dataBindings input, this change
+     * will be overwritten on the next input update.
+     */
+    setColorOpacity(path: string, opacity: number): void;
     /**
      * Apply all text runs from input (controlled keys).
      * Called on every input change or load.
      */
     private applyTextRuns;
+    /**
+     * Initialize ViewModel instance if available in the loaded file.
+     * Called once after animation loads successfully.
+     */
+    private initializeViewModel;
+    /**
+     * Get list of available ViewModel names for error messages.
+     */
+    private getAvailableViewModelNames;
+    /**
+     * Get ViewModel property information for debug logging.
+     */
+    private getViewModelPropertyInfo;
+    /**
+     * Subscribe to ViewModel property changes for two-way data binding.
+     * Emits dataBindingChange output when properties change from within the animation.
+     */
+    private subscribeToViewModelChanges;
+    /**
+     * Subscribe to changes for a specific ViewModel property.
+     * Uses multiple event APIs to maximize compatibility with @rive-app/canvas runtime versions.
+     */
+    private subscribeToPropertyChanges;
+    private buildUnsubscribeFromHandler;
+    private withLocalMutation;
+    private shouldSuppressLocalMutation;
+    private readPropertyValue;
+    private normalizeViewModelPropertyType;
+    private resolveViewModelProperty;
+    private emitDataBindingTypeMismatch;
+    private cleanupViewModelSubscriptions;
+    /**
+     * Apply all data bindings from input (controlled keys).
+     * Called on every input change or load.
+     * Auto-detects property type from ViewModel and applies the value accordingly.
+     */
+    private applyDataBindings;
+    /**
+     * Try to apply a binding value to a resolved ViewModel property.
+     * Returns true if successful, false on type mismatch.
+     */
+    private tryApplyBinding;
     /**
      * Clean up Rive instance only
      */
     private cleanupRive;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RiveCanvasComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RiveCanvasComponent, "rive-canvas", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "buffer": { "alias": "buffer"; "required": false; "isSignal": true; }; "riveFile": { "alias": "riveFile"; "required": false; "isSignal": true; }; "artboard": { "alias": "artboard"; "required": false; "isSignal": true; }; "animations": { "alias": "animations"; "required": false; "isSignal": true; }; "stateMachines": { "alias": "stateMachines"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "fit": { "alias": "fit"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; "useOffscreenRenderer": { "alias": "useOffscreenRenderer"; "required": false; "isSignal": true; }; "shouldUseIntersectionObserver": { "alias": "shouldUseIntersectionObserver"; "required": false; "isSignal": true; }; "shouldDisableRiveListeners": { "alias": "shouldDisableRiveListeners"; "required": false; "isSignal": true; }; "automaticallyHandleEvents": { "alias": "automaticallyHandleEvents"; "required": false; "isSignal": true; }; "debugMode": { "alias": "debugMode"; "required": false; "isSignal": true; }; "textRuns": { "alias": "textRuns"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "loadError": "loadError"; "stateChange": "stateChange"; "riveEvent": "riveEvent"; "riveReady": "riveReady"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RiveCanvasComponent, "rive-canvas", never, { "src": { "alias": "src"; "required": false; "isSignal": true; }; "buffer": { "alias": "buffer"; "required": false; "isSignal": true; }; "riveFile": { "alias": "riveFile"; "required": false; "isSignal": true; }; "artboard": { "alias": "artboard"; "required": false; "isSignal": true; }; "animations": { "alias": "animations"; "required": false; "isSignal": true; }; "stateMachines": { "alias": "stateMachines"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "fit": { "alias": "fit"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; "useOffscreenRenderer": { "alias": "useOffscreenRenderer"; "required": false; "isSignal": true; }; "shouldUseIntersectionObserver": { "alias": "shouldUseIntersectionObserver"; "required": false; "isSignal": true; }; "shouldDisableRiveListeners": { "alias": "shouldDisableRiveListeners"; "required": false; "isSignal": true; }; "automaticallyHandleEvents": { "alias": "automaticallyHandleEvents"; "required": false; "isSignal": true; }; "debugMode": { "alias": "debugMode"; "required": false; "isSignal": true; }; "textRuns": { "alias": "textRuns"; "required": false; "isSignal": true; }; "viewModelName": { "alias": "viewModelName"; "required": false; "isSignal": true; }; "dataBindings": { "alias": "dataBindings"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "loadError": "loadError"; "stateChange": "stateChange"; "riveEvent": "riveEvent"; "riveReady": "riveReady"; "dataBindingChange": "dataBindingChange"; }, never, never, true, never>;
 }
 
 /**
@@ -291,6 +449,7 @@ declare class RiveFileService {
  * - RIVE_1xx: Load errors (file not found, network, bad format)
  * - RIVE_2xx: Validation errors (artboard, animation, state machine mismatch)
  * - RIVE_3xx: Configuration/Usage errors (missing source, bad canvas)
+ * - RIVE_4xx: Data Binding errors (ViewModel, property not found, type mismatch)
  */
 declare enum RiveErrorCode {
     FileNotFound = "RIVE_101",
@@ -302,7 +461,10 @@ declare enum RiveErrorCode {
     InputNotFound = "RIVE_204",
     TextRunNotFound = "RIVE_205",
     NoSource = "RIVE_301",
-    InvalidCanvas = "RIVE_302"
+    InvalidCanvas = "RIVE_302",
+    ViewModelNotFound = "RIVE_401",
+    DataBindingPropertyNotFound = "RIVE_402",
+    DataBindingTypeMismatch = "RIVE_403"
 }
 
 /**
@@ -331,6 +493,48 @@ interface RiveDebugConfig {
  */
 declare function provideRiveDebug(config: RiveDebugConfig): Provider;
 
+/**
+ * Parses various color input formats into a normalized RiveColor object.
+ *
+ * Supported formats:
+ * - Hex string: '#RRGGBB' or '#RRGGBBAA'
+ * - ARGB integer: 0xAARRGGBB (32-bit integer)
+ * - RiveColor object: { r, g, b, a? }
+ *
+ * @param input - Color in any supported format
+ * @returns Normalized RiveColor object with all components in 0-255 range
+ * @throws Error if the input format is invalid
+ *
+ * @example
+ * parseRiveColor('#FF5733')         // { r: 255, g: 87, b: 51, a: 255 }
+ * parseRiveColor('#FF573380')       // { r: 255, g: 87, b: 51, a: 128 }
+ * parseRiveColor(0x80FF5733)        // { r: 255, g: 87, b: 51, a: 128 }
+ * parseRiveColor({ r: 255, g: 0, b: 0 }) // { r: 255, g: 0, b: 0, a: 255 }
+ */
+declare function parseRiveColor(input: string | number | RiveColor): RiveColor;
+/**
+ * Converts a RiveColor object to an ARGB 32-bit integer.
+ *
+ * @param color - RiveColor object
+ * @returns ARGB integer in format 0xAARRGGBB
+ *
+ * @example
+ * riveColorToArgb({ r: 255, g: 0, b: 0, a: 255 }) // 0xFFFF0000
+ * riveColorToArgb({ r: 0, g: 128, b: 255, a: 128 }) // 0x800080FF
+ */
+declare function riveColorToArgb(color: RiveColor): number;
+/**
+ * Converts a RiveColor object to a hex string.
+ *
+ * @param color - RiveColor object
+ * @returns Hex string in format '#RRGGBBAA'
+ *
+ * @example
+ * riveColorToHex({ r: 255, g: 0, b: 0, a: 255 })   // '#FF0000FF'
+ * riveColorToHex({ r: 0, g: 128, b: 255, a: 128 }) // '#0080FF80'
+ */
+declare function riveColorToHex(color: RiveColor): string;
+
 /**
  * Options for constructing a RiveLoadError with detailed context.
  */
@@ -363,5 +567,5 @@ declare class RiveValidationError extends Error {
     constructor(message: string, code: RiveErrorCode, availableOptions?: string[] | undefined, suggestion?: string | undefined);
 }
 
-export { RiveCanvasComponent, RiveErrorCode, RiveFileService, RiveLoadError, RiveValidationError, provideRiveDebug };
-export type { FileStatus, LogLevel, RiveDebugConfig, RiveErrorOptions, RiveFileParams, RiveFileState };
+export { RiveCanvasComponent, RiveErrorCode, RiveFileService, RiveLoadError, RiveValidationError, parseRiveColor, provideRiveDebug, riveColorToArgb, riveColorToHex };
+export type { DataBindingChangeEvent, DataBindingPropertyType, DataBindingValue, FileStatus, LogLevel, RiveColor, RiveDebugConfig, RiveErrorOptions, RiveFileParams, RiveFileState };