@rive-app/react-native 0.1.1-beta.1 → 0.1.2

package/nitrogen/generated/shared/c++/HybridViewModelListPropertySpec.hpp

@@ -0,0 +1,76 @@
+///
+/// HybridViewModelListPropertySpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `HybridViewModelInstanceSpec` to properly resolve imports.
+namespace margelo::nitro::rive { class HybridViewModelInstanceSpec; }
+// Forward declaration of `HybridViewModelPropertySpec` to properly resolve imports.
+namespace margelo::nitro::rive { class HybridViewModelPropertySpec; }
+
+#include <memory>
+#include "HybridViewModelInstanceSpec.hpp"
+#include <optional>
+#include <functional>
+#include "HybridViewModelPropertySpec.hpp"
+
+namespace margelo::nitro::rive {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `ViewModelListProperty`
+   * Inherit this class to create instances of `HybridViewModelListPropertySpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridViewModelListProperty: public HybridViewModelListPropertySpec {
+   * public:
+   *   HybridViewModelListProperty(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridViewModelListPropertySpec: public virtual HybridObject, public virtual HybridViewModelPropertySpec {
+    public:
+      // Constructor
+      explicit HybridViewModelListPropertySpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridViewModelListPropertySpec() override = default;
+
+    public:
+      // Properties
+      virtual double getLength() = 0;
+
+    public:
+      // Methods
+      virtual std::optional<std::shared_ptr<HybridViewModelInstanceSpec>> getInstanceAt(double index) = 0;
+      virtual void addInstance(const std::shared_ptr<HybridViewModelInstanceSpec>& instance) = 0;
+      virtual bool addInstanceAt(const std::shared_ptr<HybridViewModelInstanceSpec>& instance, double index) = 0;
+      virtual void removeInstance(const std::shared_ptr<HybridViewModelInstanceSpec>& instance) = 0;
+      virtual void removeInstanceAt(double index) = 0;
+      virtual bool swap(double index1, double index2) = 0;
+      virtual std::function<void()> addListener(const std::function<void()>& onChanged) = 0;
+      virtual void removeListeners() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "ViewModelListProperty";
+  };
+
+} // namespace margelo::nitro::rive

package/nitrogen/generated/shared/c++/HybridViewModelNumberPropertySpec.hpp

@@ -52,7 +52,7 @@ namespace margelo::nitro::rive {
 
     public:
       // Methods
-      virtual void addListener(const std::function<void(double /* value */)>& onChanged) = 0;
+      virtual std::function<void()> addListener(const std::function<void(double /* value */)>& onChanged) = 0;
       virtual void removeListeners() = 0;
 
     protected:

package/nitrogen/generated/shared/c++/HybridViewModelStringPropertySpec.hpp

@@ -53,7 +53,7 @@ namespace margelo::nitro::rive {
 
     public:
       // Methods
-      virtual void addListener(const std::function<void(const std::string& /* value */)>& onChanged) = 0;
+      virtual std::function<void()> addListener(const std::function<void(const std::string& /* value */)>& onChanged) = 0;
       virtual void removeListeners() = 0;
 
     protected:

package/nitrogen/generated/shared/c++/HybridViewModelTriggerPropertySpec.hpp

@@ -51,7 +51,7 @@ namespace margelo::nitro::rive {
 
     public:
       // Methods
-      virtual void addListener(const std::function<void()>& onChanged) = 0;
+      virtual std::function<void()> addListener(const std::function<void()>& onChanged) = 0;
       virtual void trigger() = 0;
       virtual void removeListeners() = 0;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/react-native",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.2",
   "description": "Rive React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -64,8 +64,8 @@
   },
   "homepage": "https://github.com/rive-app/rive-nitro-react-native#readme",
   "runtimeVersions": {
-    "ios": "6.12.0",
-    "android": "10.5.0"
+    "ios": "6.12.3",
+    "android": "10.5.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"

package/src/hooks/useRiveColor.ts

@@ -3,7 +3,6 @@ import type {
   ViewModelColorProperty,
   ViewModelInstance,
 } from '../specs/ViewModel.nitro';
-import { type UseRivePropertyResult } from '../types';
 import { useRiveProperty } from './useRiveProperty';
 import { RiveColor } from '../core/RiveColor';
 
@@ -11,6 +10,12 @@ const COLOR_PROPERTY_OPTIONS = {
   getProperty: (vmi: ViewModelInstance, p: string) => vmi.colorProperty(p),
 };
 
+export interface UseRiveColorResult {
+  value: RiveColor | undefined;
+  setValue: (value: RiveColor | string) => void;
+  error: Error | null;
+}
+
 /**
  * Hook for interacting with color ViewModel instance properties.
  *
@@ -21,9 +26,7 @@ const COLOR_PROPERTY_OPTIONS = {
 export function useRiveColor(
   path: string,
   viewModelInstance?: ViewModelInstance | null
-): UseRivePropertyResult<RiveColor> & {
-  setValue: (value: RiveColor | string) => void;
-} {
+): UseRiveColorResult {
   const [rawValue, setRawValue, error] = useRiveProperty<
     ViewModelColorProperty,
     number

package/src/hooks/useRiveList.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useState, useMemo } from 'react';
+import type { ViewModelInstance } from '../specs/ViewModel.nitro';
+import type { UseRiveListResult } from '../types';
+
+/**
+ * Hook for interacting with list ViewModel instance properties.
+ *
+ * @param path - The path to the list property
+ * @param viewModelInstance - The ViewModelInstance containing the list property
+ * @returns An object with list length, manipulation methods, and error state
+ */
+export function useRiveList(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRiveListResult {
+  const [error, setError] = useState<Error | null>(null);
+  const [revision, setRevision] = useState(0);
+
+  useEffect(() => {
+    setError(null);
+  }, [path, viewModelInstance]);
+
+  const property = useMemo(() => {
+    if (!viewModelInstance) return undefined;
+    return viewModelInstance.listProperty(path);
+  }, [viewModelInstance, path]);
+
+  useEffect(() => {
+    if (viewModelInstance && !property) {
+      setError(
+        new Error(`List property "${path}" not found in the ViewModel instance`)
+      );
+    }
+  }, [viewModelInstance, property, path]);
+
+  useEffect(() => {
+    if (!property) return;
+
+    const removeListener = property.addListener(() => {
+      setRevision((r) => r + 1);
+    });
+
+    return () => {
+      removeListener();
+      property.removeListeners();
+      property.dispose();
+    };
+  }, [property]);
+
+  const length = useMemo(() => {
+    // revision is used to trigger re-computation when list changes
+    revision;
+    return property?.length ?? 0;
+  }, [property, revision]);
+
+  const getInstanceAt = useCallback(
+    (index: number) => {
+      return property?.getInstanceAt(index);
+    },
+    [property]
+  );
+
+  const addInstance = useCallback(
+    (instance: ViewModelInstance) => {
+      property?.addInstance(instance);
+    },
+    [property]
+  );
+
+  const addInstanceAt = useCallback(
+    (instance: ViewModelInstance, index: number) => {
+      return property?.addInstanceAt(instance, index) ?? false;
+    },
+    [property]
+  );
+
+  const removeInstance = useCallback(
+    (instance: ViewModelInstance) => {
+      property?.removeInstance(instance);
+    },
+    [property]
+  );
+
+  const removeInstanceAt = useCallback(
+    (index: number) => {
+      property?.removeInstanceAt(index);
+    },
+    [property]
+  );
+
+  const swap = useCallback(
+    (index1: number, index2: number) => {
+      return property?.swap(index1, index2) ?? false;
+    },
+    [property]
+  );
+
+  return {
+    length,
+    getInstanceAt,
+    addInstance,
+    addInstanceAt,
+    removeInstance,
+    removeInstanceAt,
+    swap,
+    error,
+  };
+}

package/src/hooks/useRiveProperty.ts

@@ -28,7 +28,12 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     /** Optional override callback for property events (mainly used by triggers) */
     onPropertyEventOverride?: (...args: any[]) => void;
   }
-): [T | undefined, (value: T) => void, Error | null, P | undefined] {
+): [
+  T | undefined,
+  (value: T | ((prevValue: T | undefined) => T)) => void,
+  Error | null,
+  P | undefined,
+] {
   const [value, setValue] = useState<T | undefined>(undefined);
   const [error, setError] = useState<Error | null>(null);
 
@@ -61,25 +66,21 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
 
     // If an override callback is provided, use it.
     // Otherwise, use the default callback.
-    if (options.onPropertyEventOverride) {
-      property.addListener(options.onPropertyEventOverride);
-    } else {
-      property.addListener((newValue) => {
-        setValue(newValue);
-      });
-    }
+    const removeListener = options.onPropertyEventOverride
+      ? property.addListener(options.onPropertyEventOverride)
+      : property.addListener((newValue) => {
+          setValue(newValue);
+        });
 
-    // Cleanup: Remove listeners and dispose of the property
-    // This ensures proper cleanup of event listeners and resources
     return () => {
-      property.removeListeners();
+      removeListener();
       property.dispose();
     };
   }, [options, property]);
 
   // Set the value of the property
   const setPropertyValue = useCallback(
-    (newValue: T) => {
+    (valueOrUpdater: T | ((prevValue: T | undefined) => T)) => {
       if (!property) {
         setError(
           new Error(
@@ -87,6 +88,12 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
           )
         );
       } else {
+        const newValue =
+          typeof valueOrUpdater === 'function'
+            ? (valueOrUpdater as (prevValue: T | undefined) => T)(
+                property.value
+              )
+            : valueOrUpdater;
         property.value = newValue;
       }
     },
@@ -105,6 +112,6 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
 interface ObservableViewModelProperty<T>
   extends ViewModelProperty,
     ObservableProperty {
-  addListener: (onChanged: (value: T) => void) => void;
+  addListener: (onChanged: (value: T) => void) => () => void;
   value: T;
 }

package/src/hooks/useViewModelInstance.ts

@@ -0,0 +1,195 @@
+import { useMemo, useEffect, useRef } from 'react';
+import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
+import type { RiveFile } from '../specs/RiveFile.nitro';
+import type { RiveViewRef } from '../index';
+import { callDispose } from '../core/callDispose';
+
+export interface UseViewModelInstanceParams {
+  /**
+   * Get a specifically named instance from the ViewModel.
+   */
+  name?: string;
+  /**
+   * Create a new (blank) instance from the ViewModel.
+   */
+  useNew?: boolean;
+  /**
+   * If true, throws an error when the instance cannot be obtained.
+   * This is useful with Error Boundaries and ensures TypeScript knows
+   * the return value is non-null.
+   */
+  required?: boolean;
+  /**
+   * Called synchronously when a new instance is created, before the hook returns.
+   * Use this to set initial values that need to be available immediately.
+   * Note: This callback is excluded from deps - changing it won't recreate the instance.
+   */
+  onInit?: (instance: ViewModelInstance) => void;
+}
+
+type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
+
+function isRiveViewRef(source: ViewModelSource | null): source is RiveViewRef {
+  return (
+    source !== null && source !== undefined && 'getViewModelInstance' in source
+  );
+}
+
+function isRiveFile(source: ViewModelSource | null): source is RiveFile {
+  return (
+    source !== null &&
+    source !== undefined &&
+    'defaultArtboardViewModel' in source
+  );
+}
+
+function createInstance(
+  source: ViewModelSource | null,
+  name: string | undefined,
+  useNew: boolean
+): { instance: ViewModelInstance | null; needsDispose: boolean } {
+  if (!source) {
+    return { instance: null, needsDispose: false };
+  }
+
+  if (isRiveViewRef(source)) {
+    const vmi = source.getViewModelInstance();
+    return { instance: vmi ?? null, needsDispose: false };
+  }
+
+  if (isRiveFile(source)) {
+    const viewModel = source.defaultArtboardViewModel();
+    const vmi = viewModel?.createDefaultInstance();
+    return { instance: vmi ?? null, needsDispose: true };
+  }
+
+  // ViewModel source
+  let vmi: ViewModelInstance | undefined;
+  if (name) {
+    vmi = source.createInstanceByName(name);
+  } else if (useNew) {
+    vmi = source.createInstance();
+  } else {
+    vmi = source.createDefaultInstance();
+  }
+  return { instance: vmi ?? null, needsDispose: true };
+}
+
+/**
+ * Hook for getting a ViewModelInstance from a RiveFile, ViewModel, or RiveViewRef.
+ *
+ * @param source - The RiveFile, ViewModel, or RiveViewRef to get an instance from
+ * @param params - Configuration for which instance to retrieve (only used with ViewModel)
+ * @returns The ViewModelInstance or null if not found
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile (get default instance)
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From RiveViewRef (get auto-bound instance)
+ * const { riveViewRef, setHybridRef } = useRive();
+ * const instance = useViewModelInstance(riveViewRef);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From ViewModel
+ * const viewModel = file.viewModelByName('main');
+ * const instance = useViewModelInstance(viewModel);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a new blank instance from ViewModel
+ * const viewModel = file.viewModelByName('TodoItem');
+ * const newInstance = useViewModelInstance(viewModel, { useNew: true });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With required: true (throws if null, use with Error Boundary)
+ * const instance = useViewModelInstance(riveFile, { required: true });
+ * // instance is guaranteed to be non-null here
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With onInit to set initial values synchronously
+ * const instance = useViewModelInstance(riveFile, {
+ *   onInit: (vmi) => {
+ *     vmi.numberProperty('count').set(initialCount);
+ *     vmi.stringProperty('name').set(userName);
+ *   }
+ * });
+ * // Values are already set here
+ * ```
+ */
+export function useViewModelInstance(
+  source: ViewModelSource,
+  params: UseViewModelInstanceParams & { required: true }
+): ViewModelInstance;
+export function useViewModelInstance(
+  source: ViewModelSource | null,
+  params?: UseViewModelInstanceParams
+): ViewModelInstance | null;
+export function useViewModelInstance(
+  source: ViewModelSource | null,
+  params?: UseViewModelInstanceParams
+): ViewModelInstance | null {
+  const name = params?.name;
+  const useNew = params?.useNew ?? false;
+  const required = params?.required ?? false;
+  const onInit = params?.onInit;
+
+  const prevInstanceRef = useRef<{
+    instance: ViewModelInstance | null;
+    needsDispose: boolean;
+  } | null>(null);
+
+  const result = useMemo(() => {
+    const created = createInstance(source, name, useNew);
+    if (created.instance && onInit) {
+      onInit(created.instance);
+    }
+    return created;
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- onInit excluded intentionally
+  }, [source, name, useNew]);
+
+  // Dispose previous instance if it changed and needed disposal
+  if (
+    prevInstanceRef.current &&
+    prevInstanceRef.current.instance !== result.instance &&
+    prevInstanceRef.current.needsDispose &&
+    prevInstanceRef.current.instance
+  ) {
+    callDispose(prevInstanceRef.current.instance);
+  }
+  prevInstanceRef.current = result;
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (
+        prevInstanceRef.current?.needsDispose &&
+        prevInstanceRef.current.instance
+      ) {
+        callDispose(prevInstanceRef.current.instance);
+        prevInstanceRef.current = null;
+      }
+    };
+  }, []);
+
+  if (required && result.instance === null) {
+    throw new Error(
+      'useViewModelInstance: Failed to get ViewModelInstance. ' +
+        'Ensure the source has a valid ViewModel and instance available.'
+    );
+  }
+
+  return result.instance;
+}

package/src/index.tsx

@@ -30,6 +30,7 @@ export type {
   ViewModelEnumProperty,
   ViewModelTriggerProperty,
   ViewModelImageProperty,
+  ViewModelListProperty,
 } from './specs/ViewModel.nitro';
 export { Fit } from './core/Fit';
 export { Alignment } from './core/Alignment';
@@ -47,6 +48,9 @@ export { useRiveBoolean } from './hooks/useRiveBoolean';
 export { useRiveEnum } from './hooks/useRiveEnum';
 export { useRiveColor } from './hooks/useRiveColor';
 export { useRiveTrigger } from './hooks/useRiveTrigger';
+export { useRiveList } from './hooks/useRiveList';
+export { useViewModelInstance } from './hooks/useViewModelInstance';
 export { useRiveFile } from './hooks/useRiveFile';
 export { type RiveFileInput } from './hooks/useRiveFile';
+export { type SetValueAction } from './types';
 export { DataBindMode };

package/src/specs/ViewModel.nitro.ts

@@ -52,13 +52,16 @@ export interface ViewModelInstance
 
   /** Get an image property from the view model instance at the given path */
   imageProperty(path: string): ViewModelImageProperty | undefined;
+
+  /** Get a list property from the view model instance at the given path */
+  listProperty(path: string): ViewModelListProperty | undefined;
 }
 
 export interface ViewModelProperty
   extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {}
 
 export interface ObservableProperty {
-  /** Remove all listeners from the view model number property */
+  /** Remove all listeners from the property */
   removeListeners(): void;
 }
 
@@ -67,8 +70,8 @@ export interface ViewModelNumberProperty
     ObservableProperty {
   /** The value of the view model number property */
   value: number;
-  /** Add a listener to the view model number property */
-  addListener(onChanged: (value: number) => void): void;
+  /** Add a listener to the view model number property. Returns a function to remove the listener. */
+  addListener(onChanged: (value: number) => void): () => void;
 }
 
 export interface ViewModelStringProperty
@@ -76,8 +79,8 @@ export interface ViewModelStringProperty
     ObservableProperty {
   /** The value of the view model string property */
   value: string;
-  /** Add a listener to the view model string property */
-  addListener(onChanged: (value: string) => void): void;
+  /** Add a listener to the view model string property. Returns a function to remove the listener. */
+  addListener(onChanged: (value: string) => void): () => void;
 }
 
 export interface ViewModelBooleanProperty
@@ -85,8 +88,8 @@ export interface ViewModelBooleanProperty
     ObservableProperty {
   /** The value of the view model boolean property */
   value: boolean;
-  /** Add a listener to the view model boolean property */
-  addListener(onChanged: (value: boolean) => void): void;
+  /** Add a listener to the view model boolean property. Returns a function to remove the listener. */
+  addListener(onChanged: (value: boolean) => void): () => void;
 }
 
 export interface ViewModelColorProperty
@@ -94,8 +97,8 @@ export interface ViewModelColorProperty
     ObservableProperty {
   /** The value of the view model color property */
   value: number;
-  /** Add a listener to the view model color property */
-  addListener(onChanged: (value: number) => void): void;
+  /** Add a listener to the view model color property. Returns a function to remove the listener. */
+  addListener(onChanged: (value: number) => void): () => void;
 }
 
 export interface ViewModelEnumProperty
@@ -103,15 +106,15 @@ export interface ViewModelEnumProperty
     ObservableProperty {
   /** The value of the view model enum property */
   value: string;
-  /** Add a listener to the view model enum property */
-  addListener(onChanged: (value: string) => void): void;
+  /** Add a listener to the view model enum property. Returns a function to remove the listener. */
+  addListener(onChanged: (value: string) => void): () => void;
 }
 
 export interface ViewModelTriggerProperty
   extends ViewModelProperty,
     ObservableProperty {
-  /** Add a listener to the view model trigger property */
-  addListener(onChanged: () => void): void;
+  /** Add a listener to the view model trigger property. Returns a function to remove the listener. */
+  addListener(onChanged: () => void): () => void;
   /** Trigger the view model trigger property */
   trigger(): void;
 }
@@ -121,6 +124,31 @@ export interface ViewModelImageProperty
     ObservableProperty {
   /** Set the image property value */
   set(image: RiveImage | undefined): void;
-  /** Add a listener to the view model image property */
-  addListener(onChanged: () => void): void;
+  /** Add a listener to the view model image property. Returns a function to remove the listener. */
+  addListener(onChanged: () => void): () => void;
+}
+
+/**
+ * A list property that contains a dynamic collection of {@link ViewModelInstance} objects.
+ * @see {@link https://rive.app/docs/runtimes/data-binding#lists Rive Data Binding Lists}
+ */
+export interface ViewModelListProperty
+  extends ViewModelProperty,
+    ObservableProperty {
+  /** The number of instances in the list */
+  readonly length: number;
+  /** Get the instance at the given index */
+  getInstanceAt(index: number): ViewModelInstance | undefined;
+  /** Add an instance to the end of the list */
+  addInstance(instance: ViewModelInstance): void;
+  /** Add an instance at the given index, returns true if successful */
+  addInstanceAt(instance: ViewModelInstance, index: number): boolean;
+  /** Remove an instance from the list */
+  removeInstance(instance: ViewModelInstance): void;
+  /** Remove the instance at the given index */
+  removeInstanceAt(index: number): void;
+  /** Swap the instances at the given indices, returns true if successful */
+  swap(index1: number, index2: number): boolean;
+  /** Add a listener to be notified when the list changes. Returns a function to remove the listener. */
+  addListener(onChanged: () => void): () => void;
 }