@rive-app/react-native 0.1.1 → 0.1.3

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,6 +52,9 @@ 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
@@ -124,3 +127,28 @@ export interface ViewModelImageProperty
   /** 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;
+}

package/src/types.tsx

@@ -1,13 +1,22 @@
+/**
+ * A value or a function that computes a new value from the previous value.
+ * Similar to React's SetStateAction pattern.
+ */
+export type SetValueAction<T> = T | ((prevValue: T | undefined) => T);
+
 export interface UseRivePropertyResult<T> {
   /**
    * The current value of the property.
    */
   value: T | undefined;
   /**
-   * Set the value of the property.
-   * @param value - The value to set the property to.
+   * Set the value of the property. Accepts either a direct value or
+   * a function that receives the previous value and returns the new value.
+   * @example
+   * setValue(10) // Set to 10
+   * setValue((prev) => (prev ?? 0) + 5) // Increment by 5
    */
-  setValue: (value: T) => void;
+  setValue: (value: SetValueAction<T>) => void;
   /**
    * The error if the property is not found.
    */
@@ -32,3 +41,49 @@ export interface UseRiveTriggerResult {
 export type UseViewModelInstanceTriggerParameters = {
   onTrigger?: () => void;
 };
+
+export interface UseRiveListResult {
+  /**
+   * The number of instances in the list.
+   */
+  length: number;
+  /**
+   * Get the instance at the given index.
+   */
+  getInstanceAt: (
+    index: number
+  ) => import('./specs/ViewModel.nitro').ViewModelInstance | undefined;
+  /**
+   * Add an instance to the end of the list.
+   */
+  addInstance: (
+    instance: import('./specs/ViewModel.nitro').ViewModelInstance
+  ) => void;
+  /**
+   * Add an instance at the given index.
+   * @returns true if successful
+   */
+  addInstanceAt: (
+    instance: import('./specs/ViewModel.nitro').ViewModelInstance,
+    index: number
+  ) => boolean;
+  /**
+   * Remove an instance from the list.
+   */
+  removeInstance: (
+    instance: import('./specs/ViewModel.nitro').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;
+  /**
+   * The error if the property is not found.
+   */
+  error: Error | null;
+}