@grandgular/rive-angular 0.3.0 → 0.4.0

package/fesm2022/grandgular-rive-angular.mjs

@@ -2,7 +2,7 @@ import * as i0 from '@angular/core';
 import { inject, PLATFORM_ID, Injectable, InjectionToken, viewChild, DestroyRef, NgZone, input, output, signal, effect, untracked, ChangeDetectionStrategy, Component } from '@angular/core';
 import { isPlatformBrowser } from '@angular/common';
 import { Fit, Alignment, Layout, Rive, RiveFile, EventType } from '@rive-app/canvas';
-export { Alignment, EventType, Fit, Layout, Rive, RiveFile, StateMachineInput } from '@rive-app/canvas';
+export { Alignment, EventType, Fit, Layout, Rive, RiveFile, StateMachineInput, ViewModelInstance } from '@rive-app/canvas';
 
 /**
  * Re-export Rive SDK types for consumer convenience
@@ -61,6 +61,7 @@ class RiveValidationError extends Error {
  * - 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)
  */
 var RiveErrorCode;
 (function (RiveErrorCode) {
@@ -77,6 +78,10 @@ var RiveErrorCode;
     // Configuration Errors
     RiveErrorCode["NoSource"] = "RIVE_301";
     RiveErrorCode["InvalidCanvas"] = "RIVE_302";
+    // Data Binding Errors
+    RiveErrorCode["ViewModelNotFound"] = "RIVE_401";
+    RiveErrorCode["DataBindingPropertyNotFound"] = "RIVE_402";
+    RiveErrorCode["DataBindingTypeMismatch"] = "RIVE_403";
 })(RiveErrorCode || (RiveErrorCode = {}));
 /**
  * Template messages for each error code.
@@ -93,6 +98,9 @@ const ERROR_MESSAGES = {
     [RiveErrorCode.TextRunNotFound]: 'Text run "{name}" not found',
     [RiveErrorCode.NoSource]: 'No animation source provided',
     [RiveErrorCode.InvalidCanvas]: 'Invalid canvas element',
+    [RiveErrorCode.ViewModelNotFound]: 'ViewModel "{name}" not found',
+    [RiveErrorCode.DataBindingPropertyNotFound]: 'Data binding property "{path}" not found in ViewModel',
+    [RiveErrorCode.DataBindingTypeMismatch]: 'Data binding type mismatch for "{path}": expected {expected}, got {actual}',
 };
 /**
  * Formats an error message by replacing placeholders with actual values.
@@ -401,6 +409,123 @@ function validateConfiguration(rive, config, logger) {
     return errors;
 }
 
+/**
+ * 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 }
+ */
+function parseRiveColor(input) {
+    // If already a RiveColor object, normalize it
+    if (typeof input === 'object' && input !== null) {
+        return {
+            r: clamp(Math.round(input.r), 0, 255),
+            g: clamp(Math.round(input.g), 0, 255),
+            b: clamp(Math.round(input.b), 0, 255),
+            a: clamp(Math.round(input.a ?? 255), 0, 255),
+        };
+    }
+    // If hex string
+    if (typeof input === 'string') {
+        return parseHexColor(input);
+    }
+    // If ARGB integer
+    if (typeof input === 'number') {
+        return parseArgbInteger(input);
+    }
+    throw new Error(`Invalid color format: ${input}. Expected hex string, ARGB integer, or RiveColor object.`);
+}
+/**
+ * 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
+ */
+function riveColorToArgb(color) {
+    const a = clamp(Math.round(color.a), 0, 255);
+    const r = clamp(Math.round(color.r), 0, 255);
+    const g = clamp(Math.round(color.g), 0, 255);
+    const b = clamp(Math.round(color.b), 0, 255);
+    return ((a << 24) | (r << 16) | (g << 8) | b) >>> 0;
+}
+/**
+ * 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'
+ */
+function riveColorToHex(color) {
+    const r = clamp(Math.round(color.r), 0, 255)
+        .toString(16)
+        .padStart(2, '0');
+    const g = clamp(Math.round(color.g), 0, 255)
+        .toString(16)
+        .padStart(2, '0');
+    const b = clamp(Math.round(color.b), 0, 255)
+        .toString(16)
+        .padStart(2, '0');
+    const a = clamp(Math.round(color.a), 0, 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `#${r}${g}${b}${a}`.toUpperCase();
+}
+/**
+ * Parses a hex color string into a RiveColor object.
+ * Supports both '#RRGGBB' and '#RRGGBBAA' formats.
+ */
+function parseHexColor(hex) {
+    // Remove '#' if present
+    const cleanHex = hex.startsWith('#') ? hex.slice(1) : hex;
+    // Validate hex string
+    if (!/^[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/.test(cleanHex)) {
+        throw new Error(`Invalid hex color format: ${hex}. Expected '#RRGGBB' or '#RRGGBBAA'.`);
+    }
+    const r = parseInt(cleanHex.slice(0, 2), 16);
+    const g = parseInt(cleanHex.slice(2, 4), 16);
+    const b = parseInt(cleanHex.slice(4, 6), 16);
+    const a = cleanHex.length === 8 ? parseInt(cleanHex.slice(6, 8), 16) : 255;
+    return { r, g, b, a };
+}
+/**
+ * Parses an ARGB 32-bit integer into a RiveColor object.
+ * Format: 0xAARRGGBB
+ */
+function parseArgbInteger(argb) {
+    // Ensure it's a valid 32-bit unsigned integer
+    const value = argb >>> 0;
+    const a = (value >> 24) & 0xff;
+    const r = (value >> 16) & 0xff;
+    const g = (value >> 8) & 0xff;
+    const b = value & 0xff;
+    return { r, g, b, a };
+}
+/**
+ * Clamps a value between min and max.
+ */
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+
 /**
  * Standalone Angular component for Rive animations
  *
@@ -475,6 +600,30 @@ class RiveCanvasComponent {
      * Values are applied reactively when input changes.
      */
     textRuns = input(...(ngDevMode ? [undefined, { debugName: "textRuns" }] : []));
+    /**
+     * 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.
+     */
+    viewModelName = input(...(ngDevMode ? [undefined, { debugName: "viewModelName" }] : []));
+    /**
+     * 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
+     * }"
+     */
+    dataBindings = input(...(ngDevMode ? [undefined, { debugName: "dataBindings" }] : []));
     // Outputs (Events)
     loaded = output();
     loadError = output();
@@ -494,11 +643,18 @@ class RiveCanvasComponent {
      * Note: This fires AFTER the animation is loaded, not just instantiated.
      */
     riveReady = output();
+    /**
+     * 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.
+     */
+    dataBindingChange = output();
     // Private writable signals
     #isPlaying = signal(false, ...(ngDevMode ? [{ debugName: "#isPlaying" }] : []));
     #isPaused = signal(false, ...(ngDevMode ? [{ debugName: "#isPaused" }] : []));
     #isLoaded = signal(false, ...(ngDevMode ? [{ debugName: "#isLoaded" }] : []));
     #riveInstance = signal(null, ...(ngDevMode ? [{ debugName: "#riveInstance" }] : []));
+    #viewModelInstance = signal(null, ...(ngDevMode ? [{ debugName: "#viewModelInstance" }] : []));
     // Public readonly signals
     isPlaying = this.#isPlaying.asReadonly();
     isPaused = this.#isPaused.asReadonly();
@@ -508,12 +664,20 @@ class RiveCanvasComponent {
      * Use this to access advanced Rive SDK features.
      */
     riveInstance = this.#riveInstance.asReadonly();
+    /**
+     * 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.
+     */
+    viewModelInstance = this.#viewModelInstance.asReadonly();
     // Private state
     #rive = null;
     logger;
     resizeObserver = null;
     isInitialized = false;
     isPausedByIntersectionObserver = false;
+    #viewModelSubscriptionDisposers = new Set();
+    #localMutationSuppressions = new Map();
     retestIntersectionTimeoutId = null;
     resizeRafId = null;
     lastWidth = 0;
@@ -561,6 +725,27 @@ class RiveCanvasComponent {
                 }
             });
         });
+        // Effect to apply data bindings when input changes or animation loads
+        effect(() => {
+            const bindings = this.dataBindings();
+            const isLoaded = this.#isLoaded();
+            const vmi = this.#viewModelInstance();
+            untracked(() => {
+                if (bindings && isLoaded && vmi) {
+                    this.applyDataBindings(bindings);
+                }
+            });
+        });
+        // Effect to reinitialize ViewModel when viewModelName changes after load
+        effect(() => {
+            const viewModelName = this.viewModelName();
+            const isLoaded = this.#isLoaded();
+            untracked(() => {
+                if (isLoaded && this.#rive) {
+                    this.initializeViewModel();
+                }
+            });
+        });
         // Auto cleanup on destroy
         this.#destroyRef.onDestroy(() => {
             this.cleanupRive();
@@ -796,6 +981,8 @@ class RiveCanvasComponent {
                 animations: riveWithMetadata.animationNames,
                 stateMachines: riveWithMetadata.stateMachineNames,
             });
+            // Initialize ViewModel if available
+            this.initializeViewModel();
         }
         this.#ngZone.run(() => {
             this.#isLoaded.set(true);
@@ -1032,6 +1219,204 @@ class RiveCanvasComponent {
             }
         });
     }
+    // ========================================================================
+    // Data Binding (ViewModel) Methods
+    // ========================================================================
+    /**
+     * 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, value) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi) {
+            this.logger.warn('No ViewModel instance available');
+            return;
+        }
+        // Check if this key is controlled by dataBindings input
+        const controlledBindings = this.dataBindings();
+        if (controlledBindings && path in controlledBindings) {
+            this.logger.warn(`Data binding "${path}" is controlled by dataBindings input. This change will be overwritten on next input update.`);
+        }
+        this.#ngZone.runOutsideAngular(() => {
+            this.withLocalMutation(path, () => {
+                const resolved = this.resolveViewModelProperty(vmi, path);
+                if (!resolved) {
+                    this.logger.warn(`Data binding property "${path}" not found in ViewModel`);
+                    this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingPropertyNotFound, {
+                        path,
+                    }), RiveErrorCode.DataBindingPropertyNotFound)));
+                    return;
+                }
+                this.tryApplyBinding(path, value, resolved);
+            });
+        });
+    }
+    /**
+     * 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) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi)
+            return undefined;
+        return this.#ngZone.runOutsideAngular(() => {
+            // Try each property type
+            const colorProp = vmi.color(path);
+            if (colorProp) {
+                const argb = colorProp.value;
+                const a = (argb >> 24) & 0xff;
+                const r = (argb >> 16) & 0xff;
+                const g = (argb >> 8) & 0xff;
+                const b = argb & 0xff;
+                return { r, g, b, a };
+            }
+            const numberProp = vmi.number(path);
+            if (numberProp)
+                return numberProp.value;
+            const stringProp = vmi.string(path);
+            if (stringProp)
+                return stringProp.value;
+            const boolProp = vmi.boolean(path);
+            if (boolProp)
+                return boolProp.value;
+            const enumProp = vmi.enum(path);
+            if (enumProp)
+                return enumProp.value;
+            return 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) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi) {
+            this.logger.warn('No ViewModel instance available');
+            return;
+        }
+        this.#ngZone.runOutsideAngular(() => {
+            const triggerProp = vmi.trigger(path);
+            if (triggerProp) {
+                triggerProp.trigger();
+                this.logger.debug(`ViewModel trigger "${path}" fired`);
+            }
+            else {
+                this.logger.warn(`ViewModel trigger "${path}" not found`);
+                this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingPropertyNotFound, {
+                    path,
+                }), RiveErrorCode.DataBindingPropertyNotFound)));
+            }
+        });
+    }
+    /**
+     * 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, color) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi) {
+            this.logger.warn('No ViewModel instance available');
+            return;
+        }
+        // Check if this key is controlled by dataBindings input
+        const controlledBindings = this.dataBindings();
+        if (controlledBindings && path in controlledBindings) {
+            this.logger.warn(`Color "${path}" is controlled by dataBindings input. This change will be overwritten on next input update.`);
+        }
+        this.#ngZone.runOutsideAngular(() => {
+            this.withLocalMutation(path, () => {
+                const colorProp = vmi.color(path);
+                if (!colorProp) {
+                    this.logger.warn(`Color property "${path}" not found in ViewModel`);
+                    this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingPropertyNotFound, {
+                        path,
+                    }), RiveErrorCode.DataBindingPropertyNotFound)));
+                    return;
+                }
+                try {
+                    const parsedColor = parseRiveColor(color);
+                    colorProp.rgba(parsedColor.r, parsedColor.g, parsedColor.b, parsedColor.a);
+                    this.logger.debug(`Color "${path}" set to:`, parsedColor);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to set color "${path}":`, error);
+                    this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(`Failed to parse color value for "${path}": ${error instanceof Error ? error.message : String(error)}`, RiveErrorCode.DataBindingTypeMismatch)));
+                }
+            });
+        });
+    }
+    /**
+     * Get a color value from the ViewModel.
+     * Returns undefined if the property doesn't exist or ViewModel is not loaded.
+     */
+    getColor(path) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi)
+            return undefined;
+        return this.#ngZone.runOutsideAngular(() => {
+            const colorProp = vmi.color(path);
+            if (!colorProp)
+                return undefined;
+            const argb = colorProp.value;
+            const a = (argb >> 24) & 0xff;
+            const r = (argb >> 16) & 0xff;
+            const g = (argb >> 8) & 0xff;
+            const b = argb & 0xff;
+            return { r, g, b, a };
+        });
+    }
+    /**
+     * 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, r, g, b, a = 255) {
+        this.setColor(path, { r, g, b, a });
+    }
+    /**
+     * 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, opacity) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi) {
+            this.logger.warn('No ViewModel instance available');
+            return;
+        }
+        // Validate opacity range
+        if (opacity < 0 || opacity > 1) {
+            this.logger.warn(`Invalid opacity value ${opacity}: must be between 0.0 and 1.0`);
+            this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(`Invalid opacity value for "${path}": ${opacity}. Expected value between 0.0 and 1.0.`, RiveErrorCode.DataBindingTypeMismatch)));
+            return;
+        }
+        // Check if this key is controlled by dataBindings input
+        const controlledBindings = this.dataBindings();
+        if (controlledBindings && path in controlledBindings) {
+            this.logger.warn(`Color "${path}" is controlled by dataBindings input. This change will be overwritten on next input update.`);
+        }
+        this.#ngZone.runOutsideAngular(() => {
+            this.withLocalMutation(path, () => {
+                const colorProp = vmi.color(path);
+                if (!colorProp) {
+                    this.logger.warn(`Color property "${path}" not found in ViewModel`);
+                    this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingPropertyNotFound, {
+                        path,
+                    }), RiveErrorCode.DataBindingPropertyNotFound)));
+                    return;
+                }
+                colorProp.opacity(opacity);
+                this.logger.debug(`Color "${path}" opacity set to ${opacity}`);
+            });
+        });
+    }
     /**
      * Apply all text runs from input (controlled keys).
      * Called on every input change or load.
@@ -1050,10 +1435,450 @@ class RiveCanvasComponent {
             }
         });
     }
+    /**
+     * Initialize ViewModel instance if available in the loaded file.
+     * Called once after animation loads successfully.
+     */
+    initializeViewModel() {
+        if (!this.#rive)
+            return;
+        this.#ngZone.runOutsideAngular(() => {
+            try {
+                const viewModelName = this.viewModelName();
+                let viewModel;
+                // Get ViewModel by name or use default
+                if (viewModelName) {
+                    viewModel = this.#rive.viewModelByName(viewModelName);
+                    if (!viewModel) {
+                        this.logger.warn(`ViewModel "${viewModelName}" not found. Available ViewModels:`, this.getAvailableViewModelNames());
+                        this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.ViewModelNotFound, {
+                            name: viewModelName,
+                        }), RiveErrorCode.ViewModelNotFound, this.getAvailableViewModelNames())));
+                        return;
+                    }
+                }
+                else {
+                    viewModel = this.#rive.defaultViewModel();
+                }
+                // If no ViewModel found (file doesn't use ViewModels), that's OK
+                if (!viewModel) {
+                    this.logger.debug('No ViewModel found in file (file may not use ViewModels)');
+                    return;
+                }
+                // Get ViewModel instance
+                const viewModelInstance = viewModel.instance();
+                if (!viewModelInstance) {
+                    this.logger.warn('Failed to create ViewModel instance');
+                    return;
+                }
+                // Bind to artboard
+                this.#rive.bindViewModelInstance(viewModelInstance);
+                // Update signal
+                this.#ngZone.run(() => {
+                    this.#viewModelInstance.set(viewModelInstance);
+                });
+                // Log ViewModel info in debug mode
+                this.logger.debug('ViewModel initialized:', {
+                    name: viewModel.name,
+                    properties: this.getViewModelPropertyInfo(viewModelInstance),
+                });
+                // Subscribe to ViewModel property changes for two-way binding
+                this.subscribeToViewModelChanges(viewModelInstance);
+            }
+            catch (error) {
+                this.logger.error('Error initializing ViewModel:', error);
+            }
+        });
+    }
+    /**
+     * Get list of available ViewModel names for error messages.
+     */
+    getAvailableViewModelNames() {
+        if (!this.#rive)
+            return [];
+        const names = [];
+        const count = this.#rive.viewModelCount;
+        for (let i = 0; i < count; i++) {
+            const vm = this.#rive.viewModelByIndex(i);
+            if (vm)
+                names.push(vm.name);
+        }
+        return names;
+    }
+    /**
+     * Get ViewModel property information for debug logging.
+     */
+    getViewModelPropertyInfo(vmi) {
+        const info = {};
+        try {
+            const properties = vmi.properties;
+            for (const prop of properties) {
+                // Property has name and type
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const propAny = prop;
+                const propertyType = this.normalizeViewModelPropertyType(propAny?.type);
+                info[propAny.name || 'unknown'] = propertyType ?? (propAny.type || 'unknown');
+            }
+        }
+        catch (error) {
+            this.logger.warn('Failed to get ViewModel property info:', error);
+        }
+        return info;
+    }
+    /**
+     * Subscribe to ViewModel property changes for two-way data binding.
+     * Emits dataBindingChange output when properties change from within the animation.
+     */
+    subscribeToViewModelChanges(vmi) {
+        this.cleanupViewModelSubscriptions();
+        const properties = vmi.properties ?? [];
+        if (!Array.isArray(properties)) {
+            return;
+        }
+        for (const property of properties) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const propertyAny = property;
+            const path = propertyAny?.name;
+            if (typeof path !== 'string') {
+                continue;
+            }
+            const resolved = this.resolveViewModelProperty(vmi, path);
+            if (!resolved) {
+                continue;
+            }
+            const subscription = this.subscribeToPropertyChanges(path, resolved.type, resolved.accessor);
+            if (subscription) {
+                this.#viewModelSubscriptionDisposers.add(subscription);
+            }
+        }
+    }
+    /**
+     * Subscribe to changes for a specific ViewModel property.
+     * Uses multiple event APIs to maximize compatibility with @rive-app/canvas runtime versions.
+     */
+    subscribeToPropertyChanges(path, propertyType, property) {
+        const propertyAny = property;
+        if (!propertyAny) {
+            return undefined;
+        }
+        const callback = () => {
+            if (this.shouldSuppressLocalMutation(path)) {
+                return;
+            }
+            const value = this.readPropertyValue(propertyType, propertyAny);
+            if (value === undefined)
+                return;
+            this.#ngZone.run(() => {
+                this.dataBindingChange.emit({
+                    path,
+                    value,
+                    propertyType,
+                });
+            });
+        };
+        let unsubscribe;
+        try {
+            if (typeof propertyAny.on === 'function') {
+                try {
+                    const handler = propertyAny.on(callback);
+                    unsubscribe = this.buildUnsubscribeFromHandler(propertyAny, callback, handler);
+                }
+                catch {
+                    const handler = propertyAny.on('change', callback);
+                    unsubscribe = this.buildUnsubscribeFromHandler(propertyAny, callback, handler, true);
+                }
+            }
+            else if (typeof propertyAny.subscribe === 'function') {
+                const handler = propertyAny.subscribe(callback);
+                unsubscribe = this.buildUnsubscribeFromHandler(propertyAny, callback, handler);
+            }
+            else if (typeof propertyAny.addEventListener === 'function') {
+                propertyAny.addEventListener('change', callback);
+                unsubscribe = () => propertyAny.removeEventListener?.('change', callback);
+            }
+            else if (typeof propertyAny.addListener === 'function') {
+                propertyAny.addListener('change', callback);
+                unsubscribe = () => propertyAny.removeListener?.('change', callback);
+            }
+            else if (typeof propertyAny.onChange === 'function') {
+                const handler = propertyAny.onChange(callback);
+                unsubscribe = this.buildUnsubscribeFromHandler(propertyAny, callback, handler);
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Failed to subscribe to ViewModel property "${path}":`, error);
+        }
+        if (!unsubscribe) {
+            this.logger.warn(`No supported subscription API found for ViewModel property "${path}"`);
+        }
+        return unsubscribe;
+    }
+    buildUnsubscribeFromHandler(property, callback, handler, useLegacyEventApi) {
+        if (typeof handler === 'function') {
+            return handler;
+        }
+        if (handler && typeof handler === 'object' && 'unsubscribe' in handler && typeof handler.unsubscribe === 'function') {
+            return () => handler.unsubscribe();
+        }
+        if (handler && typeof handler === 'object' && 'dispose' in handler && typeof handler.dispose === 'function') {
+            return () => handler.dispose();
+        }
+        if (typeof property.off === 'function') {
+            return useLegacyEventApi
+                ? () => property.off('change', callback)
+                : () => property.off(callback);
+        }
+        if (typeof property.remove === 'function') {
+            return useLegacyEventApi
+                ? () => property.remove('change', callback)
+                : () => property.remove(callback);
+        }
+        if (typeof property.removeListener === 'function') {
+            return useLegacyEventApi
+                ? () => property.removeListener('change', callback)
+                : () => property.removeListener(callback);
+        }
+        if (typeof property.unsubscribe === 'function') {
+            return () => property.unsubscribe();
+        }
+        return undefined;
+    }
+    withLocalMutation(path, fn) {
+        const previous = this.#localMutationSuppressions.get(path) ?? 0;
+        this.#localMutationSuppressions.set(path, previous + 1);
+        try {
+            fn();
+        }
+        finally {
+            setTimeout(() => {
+                const current = this.#localMutationSuppressions.get(path) ?? 0;
+                if (current <= 1) {
+                    this.#localMutationSuppressions.delete(path);
+                }
+                else {
+                    this.#localMutationSuppressions.set(path, current - 1);
+                }
+            });
+        }
+    }
+    shouldSuppressLocalMutation(path) {
+        const current = this.#localMutationSuppressions.get(path);
+        if (current === undefined || current <= 0) {
+            return false;
+        }
+        if (current <= 1) {
+            this.#localMutationSuppressions.delete(path);
+        }
+        else {
+            this.#localMutationSuppressions.set(path, current - 1);
+        }
+        return true;
+    }
+    readPropertyValue(propertyType, property) {
+        if (propertyType === 'color') {
+            if (!property || typeof property.value !== 'number')
+                return undefined;
+            const argb = property.value;
+            const a = (argb >> 24) & 0xff;
+            const r = (argb >> 16) & 0xff;
+            const g = (argb >> 8) & 0xff;
+            const b = argb & 0xff;
+            return { r, g, b, a };
+        }
+        if (propertyType === 'number' && typeof property.value === 'number') {
+            return property.value;
+        }
+        if (propertyType === 'string' && typeof property.value === 'string') {
+            return property.value;
+        }
+        if (propertyType === 'boolean' && typeof property.value === 'boolean') {
+            return property.value;
+        }
+        if (propertyType === 'enum' && typeof property.value === 'string') {
+            return property.value;
+        }
+        if (propertyType === 'trigger') {
+            // Triggers don't have a meaningful value, but we return true to indicate the trigger fired
+            return true;
+        }
+        return undefined;
+    }
+    normalizeViewModelPropertyType(type) {
+        if (typeof type !== 'string') {
+            return null;
+        }
+        const normalized = type.toLowerCase();
+        if (normalized.includes('color'))
+            return 'color';
+        if (normalized.includes('number'))
+            return 'number';
+        if (normalized.includes('string'))
+            return 'string';
+        if (normalized.includes('boolean'))
+            return 'boolean';
+        if (normalized.includes('enum'))
+            return 'enum';
+        if (normalized.includes('trigger'))
+            return 'trigger';
+        return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolveViewModelProperty(vmi, path) {
+        const color = vmi.color(path);
+        if (color)
+            return { accessor: color, type: 'color' };
+        const number = vmi.number(path);
+        if (number)
+            return { accessor: number, type: 'number' };
+        const string = vmi.string(path);
+        if (string)
+            return { accessor: string, type: 'string' };
+        const bool = vmi.boolean(path);
+        if (bool)
+            return { accessor: bool, type: 'boolean' };
+        const enumProp = vmi.enum(path);
+        if (enumProp)
+            return { accessor: enumProp, type: 'enum' };
+        const trigger = vmi.trigger(path);
+        if (trigger)
+            return { accessor: trigger, type: 'trigger' };
+        return null;
+    }
+    emitDataBindingTypeMismatch(path, expectedType, actualType) {
+        this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingTypeMismatch, {
+            path,
+            expected: expectedType,
+            actual: actualType,
+        }), RiveErrorCode.DataBindingTypeMismatch)));
+    }
+    cleanupViewModelSubscriptions() {
+        this.#viewModelSubscriptionDisposers.forEach((disposer) => {
+            try {
+                disposer();
+            }
+            catch (error) {
+                this.logger.warn('Error during ViewModel subscription cleanup:', error);
+            }
+        });
+        this.#viewModelSubscriptionDisposers.clear();
+    }
+    /**
+     * 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.
+     */
+    applyDataBindings(bindings) {
+        const vmi = this.#viewModelInstance();
+        if (!vmi)
+            return;
+        this.#ngZone.runOutsideAngular(() => {
+            for (const [path, value] of Object.entries(bindings)) {
+                try {
+                    const resolved = this.resolveViewModelProperty(vmi, path);
+                    if (!resolved) {
+                        this.logger.warn(`Data binding property "${path}" not found in ViewModel`);
+                        this.#ngZone.run(() => this.loadError.emit(new RiveValidationError(formatErrorMessage(RiveErrorCode.DataBindingPropertyNotFound, {
+                            path,
+                        }), RiveErrorCode.DataBindingPropertyNotFound)));
+                        continue;
+                    }
+                    let applied = false;
+                    this.withLocalMutation(path, () => {
+                        applied = this.tryApplyBinding(path, value, resolved);
+                    });
+                    if (applied) {
+                        this.logger.debug(`Data binding "${path}" set to:`, value);
+                    }
+                    else {
+                        this.logger.warn(`Data binding property "${path}" has a type mismatch for value type ${typeof value}`);
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to set data binding "${path}":`, error);
+                }
+            }
+        });
+    }
+    /**
+     * Try to apply a binding value to a resolved ViewModel property.
+     * Returns true if successful, false on type mismatch.
+     */
+    tryApplyBinding(path, value, resolved) {
+        const { accessor, type } = resolved;
+        if (type === 'color') {
+            if (typeof value === 'object' && value !== null && 'r' in value) {
+                // RiveColor object
+                const color = value;
+                accessor.rgba(color.r, color.g, color.b, color.a);
+                return true;
+            }
+            if (typeof value === 'string' || typeof value === 'number') {
+                // Hex string or ARGB integer
+                const color = parseRiveColor(value);
+                accessor.rgba(color.r, color.g, color.b, color.a);
+                return true;
+            }
+            this.logger.warn(`Invalid color value for "${path}": expected string, number, or RiveColor`);
+            this.emitDataBindingTypeMismatch(path, type, typeof value);
+            return false;
+        }
+        if (type === 'number') {
+            if (typeof value === 'number') {
+                accessor.value = value;
+                return true;
+            }
+            this.logger.warn(`Invalid number value for "${path}": expected number, got ${typeof value}`);
+            this.emitDataBindingTypeMismatch(path, type, typeof value);
+            return false;
+        }
+        if (type === 'string') {
+            if (typeof value === 'string') {
+                accessor.value = value;
+                return true;
+            }
+            this.logger.warn(`Invalid string value for "${path}": expected string, got ${typeof value}`);
+            this.emitDataBindingTypeMismatch(path, type, typeof value);
+            return false;
+        }
+        if (type === 'boolean') {
+            if (typeof value === 'boolean') {
+                accessor.value = value;
+                return true;
+            }
+            this.logger.warn(`Invalid boolean value for "${path}": expected boolean, got ${typeof value}`);
+            this.emitDataBindingTypeMismatch(path, type, typeof value);
+            return false;
+        }
+        if (type === 'enum') {
+            if (typeof value === 'string') {
+                accessor.value = value;
+                return true;
+            }
+            this.logger.warn(`Invalid enum value for "${path}": expected string, got ${typeof value}`);
+            this.emitDataBindingTypeMismatch(path, type, typeof value);
+            return false;
+        }
+        if (type === 'trigger') {
+            this.logger.warn(`Cannot set trigger property "${path}" via setDataBinding`);
+            return false;
+        }
+        return false;
+    }
     /**
      * Clean up Rive instance only
      */
     cleanupRive() {
+        this.cleanupViewModelSubscriptions();
+        this.#localMutationSuppressions.clear();
+        const vmi = this.#viewModelInstance();
+        if (vmi) {
+            try {
+                vmi.cleanup();
+            }
+            catch (error) {
+                this.logger.warn('Error during ViewModel cleanup:', error);
+            }
+        }
         if (this.#rive) {
             try {
                 this.#rive.cleanup();
@@ -1065,12 +1890,13 @@ class RiveCanvasComponent {
         }
         // Reset signals
         this.#riveInstance.set(null);
+        this.#viewModelInstance.set(null);
         this.#isLoaded.set(false);
         this.#isPlaying.set(false);
         this.#isPaused.set(false);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.4", ngImport: i0, type: RiveCanvasComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "21.1.4", type: RiveCanvasComponent, isStandalone: true, selector: "rive-canvas", inputs: { src: { classPropertyName: "src", publicName: "src", isSignal: true, isRequired: false, transformFunction: null }, buffer: { classPropertyName: "buffer", publicName: "buffer", isSignal: true, isRequired: false, transformFunction: null }, riveFile: { classPropertyName: "riveFile", publicName: "riveFile", isSignal: true, isRequired: false, transformFunction: null }, artboard: { classPropertyName: "artboard", publicName: "artboard", isSignal: true, isRequired: false, transformFunction: null }, animations: { classPropertyName: "animations", publicName: "animations", isSignal: true, isRequired: false, transformFunction: null }, stateMachines: { classPropertyName: "stateMachines", publicName: "stateMachines", isSignal: true, isRequired: false, transformFunction: null }, autoplay: { classPropertyName: "autoplay", publicName: "autoplay", isSignal: true, isRequired: false, transformFunction: null }, fit: { classPropertyName: "fit", publicName: "fit", isSignal: true, isRequired: false, transformFunction: null }, alignment: { classPropertyName: "alignment", publicName: "alignment", isSignal: true, isRequired: false, transformFunction: null }, useOffscreenRenderer: { classPropertyName: "useOffscreenRenderer", publicName: "useOffscreenRenderer", isSignal: true, isRequired: false, transformFunction: null }, shouldUseIntersectionObserver: { classPropertyName: "shouldUseIntersectionObserver", publicName: "shouldUseIntersectionObserver", isSignal: true, isRequired: false, transformFunction: null }, shouldDisableRiveListeners: { classPropertyName: "shouldDisableRiveListeners", publicName: "shouldDisableRiveListeners", isSignal: true, isRequired: false, transformFunction: null }, automaticallyHandleEvents: { classPropertyName: "automaticallyHandleEvents", publicName: "automaticallyHandleEvents", isSignal: true, isRequired: false, transformFunction: null }, debugMode: { classPropertyName: "debugMode", publicName: "debugMode", isSignal: true, isRequired: false, transformFunction: null }, textRuns: { classPropertyName: "textRuns", publicName: "textRuns", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { loaded: "loaded", loadError: "loadError", stateChange: "stateChange", riveEvent: "riveEvent", riveReady: "riveReady" }, viewQueries: [{ propertyName: "canvas", first: true, predicate: ["canvas"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.2.0", version: "21.1.4", type: RiveCanvasComponent, isStandalone: true, selector: "rive-canvas", inputs: { src: { classPropertyName: "src", publicName: "src", isSignal: true, isRequired: false, transformFunction: null }, buffer: { classPropertyName: "buffer", publicName: "buffer", isSignal: true, isRequired: false, transformFunction: null }, riveFile: { classPropertyName: "riveFile", publicName: "riveFile", isSignal: true, isRequired: false, transformFunction: null }, artboard: { classPropertyName: "artboard", publicName: "artboard", isSignal: true, isRequired: false, transformFunction: null }, animations: { classPropertyName: "animations", publicName: "animations", isSignal: true, isRequired: false, transformFunction: null }, stateMachines: { classPropertyName: "stateMachines", publicName: "stateMachines", isSignal: true, isRequired: false, transformFunction: null }, autoplay: { classPropertyName: "autoplay", publicName: "autoplay", isSignal: true, isRequired: false, transformFunction: null }, fit: { classPropertyName: "fit", publicName: "fit", isSignal: true, isRequired: false, transformFunction: null }, alignment: { classPropertyName: "alignment", publicName: "alignment", isSignal: true, isRequired: false, transformFunction: null }, useOffscreenRenderer: { classPropertyName: "useOffscreenRenderer", publicName: "useOffscreenRenderer", isSignal: true, isRequired: false, transformFunction: null }, shouldUseIntersectionObserver: { classPropertyName: "shouldUseIntersectionObserver", publicName: "shouldUseIntersectionObserver", isSignal: true, isRequired: false, transformFunction: null }, shouldDisableRiveListeners: { classPropertyName: "shouldDisableRiveListeners", publicName: "shouldDisableRiveListeners", isSignal: true, isRequired: false, transformFunction: null }, automaticallyHandleEvents: { classPropertyName: "automaticallyHandleEvents", publicName: "automaticallyHandleEvents", isSignal: true, isRequired: false, transformFunction: null }, debugMode: { classPropertyName: "debugMode", publicName: "debugMode", isSignal: true, isRequired: false, transformFunction: null }, textRuns: { classPropertyName: "textRuns", publicName: "textRuns", isSignal: true, isRequired: false, transformFunction: null }, viewModelName: { classPropertyName: "viewModelName", publicName: "viewModelName", isSignal: true, isRequired: false, transformFunction: null }, dataBindings: { classPropertyName: "dataBindings", publicName: "dataBindings", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { loaded: "loaded", loadError: "loadError", stateChange: "stateChange", riveEvent: "riveEvent", riveReady: "riveReady", dataBindingChange: "dataBindingChange" }, viewQueries: [{ propertyName: "canvas", first: true, predicate: ["canvas"], descendants: true, isSignal: true }], ngImport: i0, template: `
     <canvas #canvas [style.width.%]="100" [style.height.%]="100"></canvas>
   `, isInline: true, styles: [":host{display:block;width:100%;height:100%}canvas{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
@@ -1079,7 +1905,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImpor
             args: [{ selector: 'rive-canvas', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, template: `
     <canvas #canvas [style.width.%]="100" [style.height.%]="100"></canvas>
   `, styles: [":host{display:block;width:100%;height:100%}canvas{display:block}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { canvas: [{ type: i0.ViewChild, args: ['canvas', { isSignal: true }] }], src: [{ type: i0.Input, args: [{ isSignal: true, alias: "src", required: false }] }], buffer: [{ type: i0.Input, args: [{ isSignal: true, alias: "buffer", required: false }] }], riveFile: [{ type: i0.Input, args: [{ isSignal: true, alias: "riveFile", required: false }] }], artboard: [{ type: i0.Input, args: [{ isSignal: true, alias: "artboard", required: false }] }], animations: [{ type: i0.Input, args: [{ isSignal: true, alias: "animations", required: false }] }], stateMachines: [{ type: i0.Input, args: [{ isSignal: true, alias: "stateMachines", required: false }] }], autoplay: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoplay", required: false }] }], fit: [{ type: i0.Input, args: [{ isSignal: true, alias: "fit", required: false }] }], alignment: [{ type: i0.Input, args: [{ isSignal: true, alias: "alignment", required: false }] }], useOffscreenRenderer: [{ type: i0.Input, args: [{ isSignal: true, alias: "useOffscreenRenderer", required: false }] }], shouldUseIntersectionObserver: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldUseIntersectionObserver", required: false }] }], shouldDisableRiveListeners: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldDisableRiveListeners", required: false }] }], automaticallyHandleEvents: [{ type: i0.Input, args: [{ isSignal: true, alias: "automaticallyHandleEvents", required: false }] }], debugMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "debugMode", required: false }] }], textRuns: [{ type: i0.Input, args: [{ isSignal: true, alias: "textRuns", required: false }] }], loaded: [{ type: i0.Output, args: ["loaded"] }], loadError: [{ type: i0.Output, args: ["loadError"] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }], riveEvent: [{ type: i0.Output, args: ["riveEvent"] }], riveReady: [{ type: i0.Output, args: ["riveReady"] }] } });
+        }], ctorParameters: () => [], propDecorators: { canvas: [{ type: i0.ViewChild, args: ['canvas', { isSignal: true }] }], src: [{ type: i0.Input, args: [{ isSignal: true, alias: "src", required: false }] }], buffer: [{ type: i0.Input, args: [{ isSignal: true, alias: "buffer", required: false }] }], riveFile: [{ type: i0.Input, args: [{ isSignal: true, alias: "riveFile", required: false }] }], artboard: [{ type: i0.Input, args: [{ isSignal: true, alias: "artboard", required: false }] }], animations: [{ type: i0.Input, args: [{ isSignal: true, alias: "animations", required: false }] }], stateMachines: [{ type: i0.Input, args: [{ isSignal: true, alias: "stateMachines", required: false }] }], autoplay: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoplay", required: false }] }], fit: [{ type: i0.Input, args: [{ isSignal: true, alias: "fit", required: false }] }], alignment: [{ type: i0.Input, args: [{ isSignal: true, alias: "alignment", required: false }] }], useOffscreenRenderer: [{ type: i0.Input, args: [{ isSignal: true, alias: "useOffscreenRenderer", required: false }] }], shouldUseIntersectionObserver: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldUseIntersectionObserver", required: false }] }], shouldDisableRiveListeners: [{ type: i0.Input, args: [{ isSignal: true, alias: "shouldDisableRiveListeners", required: false }] }], automaticallyHandleEvents: [{ type: i0.Input, args: [{ isSignal: true, alias: "automaticallyHandleEvents", required: false }] }], debugMode: [{ type: i0.Input, args: [{ isSignal: true, alias: "debugMode", required: false }] }], textRuns: [{ type: i0.Input, args: [{ isSignal: true, alias: "textRuns", required: false }] }], viewModelName: [{ type: i0.Input, args: [{ isSignal: true, alias: "viewModelName", required: false }] }], dataBindings: [{ type: i0.Input, args: [{ isSignal: true, alias: "dataBindings", required: false }] }], loaded: [{ type: i0.Output, args: ["loaded"] }], loadError: [{ type: i0.Output, args: ["loadError"] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }], riveEvent: [{ type: i0.Output, args: ["riveEvent"] }], riveReady: [{ type: i0.Output, args: ["riveReady"] }], dataBindingChange: [{ type: i0.Output, args: ["dataBindingChange"] }] } });
 
 /**
  * Service for preloading and caching Rive files.
@@ -1294,5 +2120,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.4", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { RiveCanvasComponent, RiveErrorCode, RiveFileService, RiveLoadError, RiveValidationError, provideRiveDebug };
+export { RiveCanvasComponent, RiveErrorCode, RiveFileService, RiveLoadError, RiveValidationError, parseRiveColor, provideRiveDebug, riveColorToArgb, riveColorToHex };
 //# sourceMappingURL=grandgular-rive-angular.mjs.map