@rive-app/react-native 0.1.1-beta.0

package/src/core/callDispose.ts

@@ -0,0 +1,18 @@
+const NITRO_DISPOSE_ERROR = 'failed to define internal native state property';
+
+interface Disposable {
+  dispose(): void;
+}
+
+/** Safely calls dispose(), ignoring errors from https://github.com/mrousavy/nitro/issues/1083 */
+export function callDispose(obj: Disposable): void {
+  try {
+    obj.dispose();
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : String(error ?? '');
+    if (!message.includes(NITRO_DISPOSE_ERROR)) {
+      throw error;
+    }
+  }
+}

package/src/hooks/useRive.ts

@@ -0,0 +1,56 @@
+import { useRef, useCallback, useState } from 'react';
+import type { RiveViewRef } from '@rive-app/react-native';
+
+export function useRive() {
+  const riveRef = useRef<RiveViewRef>(null);
+  const [riveViewRef, setRiveViewRef] = useState<RiveViewRef | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const setRef = useCallback((node: RiveViewRef | null) => {
+    if (riveRef.current !== node) {
+      riveRef.current = node;
+
+      // Clear any existing timeout
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      const timeout = new Promise((_, reject) => {
+        timeoutRef.current = setTimeout(() => {
+          reject(new Error('Rive view ready timeout'));
+        }, 5000);
+      });
+
+      // TODO: Need to clear out the awaitViewReady promise if it times out
+      // or add this timeout natively and return false
+      Promise.race([node?.awaitViewReady(), timeout])
+        .then((result) => {
+          if (result === true) {
+            setRiveViewRef(node);
+          } else {
+            console.warn('Rive view ready check returned false');
+            setRiveViewRef(null);
+          }
+        })
+        .catch((error) => {
+          console.warn('Failed to initialize Rive view:', error);
+          setRiveViewRef(null);
+        })
+        .finally(() => {
+          // Clear the timeout in both success and error cases
+          if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+          }
+        });
+    }
+  }, []);
+
+  return {
+    riveRef,
+    riveViewRef,
+    setHybridRef: {
+      f: setRef,
+    },
+  };
+}

package/src/hooks/useRiveBoolean.ts

@@ -0,0 +1,28 @@
+import {
+  type ViewModelBooleanProperty,
+  type ViewModelInstance,
+} from '../specs/ViewModel.nitro';
+import type { UseRivePropertyResult } from '../types';
+import { useRiveProperty } from './useRiveProperty';
+
+const BOOLEAN_PROPERTY_OPTIONS = {
+  getProperty: (vmi: ViewModelInstance, p: string) => vmi.booleanProperty(p),
+};
+
+/**
+ * Hook for interacting with boolean ViewModel instance properties.
+ *
+ * @param path - The path to the boolean property
+ * @param viewModelInstance - The ViewModelInstance containing the boolean property to operate on
+ * @returns An object with the boolean value, a setter function, and an error if the property is not found
+ */
+export function useRiveBoolean(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRivePropertyResult<boolean> {
+  const [value, setValue, error] = useRiveProperty<
+    ViewModelBooleanProperty,
+    boolean
+  >(viewModelInstance, path, BOOLEAN_PROPERTY_OPTIONS);
+  return { value, setValue, error };
+}

package/src/hooks/useRiveColor.ts

@@ -0,0 +1,47 @@
+import { useCallback } from 'react';
+import type {
+  ViewModelColorProperty,
+  ViewModelInstance,
+} from '../specs/ViewModel.nitro';
+import { type UseRivePropertyResult } from '../types';
+import { useRiveProperty } from './useRiveProperty';
+import { RiveColor } from '../core/RiveColor';
+
+const COLOR_PROPERTY_OPTIONS = {
+  getProperty: (vmi: ViewModelInstance, p: string) => vmi.colorProperty(p),
+};
+
+/**
+ * Hook for interacting with color ViewModel instance properties.
+ *
+ * @param path - The path to the color property
+ * @param viewModelInstance - The ViewModelInstance containing the color property to operate on
+ * @returns An object with the color value as RGBA, a setter function that accepts either RGBA or hex string, and an error if the property is not found
+ */
+export function useRiveColor(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRivePropertyResult<RiveColor> & {
+  setValue: (value: RiveColor | string) => void;
+} {
+  const [rawValue, setRawValue, error] = useRiveProperty<
+    ViewModelColorProperty,
+    number
+  >(viewModelInstance, path, COLOR_PROPERTY_OPTIONS);
+
+  const value =
+    rawValue !== undefined ? RiveColor.fromInt(rawValue) : undefined;
+
+  const setValue = useCallback(
+    (newValue: RiveColor | string) => {
+      const color =
+        typeof newValue === 'string'
+          ? RiveColor.fromHexString(newValue)
+          : newValue;
+      setRawValue(color.toInt());
+    },
+    [setRawValue]
+  );
+
+  return { value, setValue, error };
+}

package/src/hooks/useRiveEnum.ts

@@ -0,0 +1,27 @@
+import { useCallback } from 'react';
+import {
+  type ViewModelEnumProperty,
+  type ViewModelInstance,
+} from '../specs/ViewModel.nitro';
+import type { UseRivePropertyResult } from '../types';
+import { useRiveProperty } from './useRiveProperty';
+
+/**
+ * Hook for interacting with enum ViewModel instance properties.
+ *
+ * @param path - The path to the enum property
+ * @param viewModelInstance - The ViewModelInstance containing the enum property to operate on
+ * @returns An object with the enum value, a setter function, and an error if the property is not found
+ */
+export function useRiveEnum(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRivePropertyResult<string> {
+  const [value, setValue, error] = useRiveProperty<
+    ViewModelEnumProperty,
+    string
+  >(viewModelInstance, path, {
+    getProperty: useCallback((vmi, p) => vmi.enumProperty(p), []),
+  });
+  return { value, setValue, error };
+}

package/src/hooks/useRiveFile.ts

@@ -0,0 +1,184 @@
+import { useState, useEffect, useMemo, useRef } from 'react';
+import { Image } from 'react-native';
+import { RiveFileFactory } from '../core/RiveFile';
+import { callDispose } from '../core/callDispose';
+import type {
+  RiveFile,
+  ResolvedReferencedAsset,
+} from '../specs/RiveFile.nitro';
+import type { RiveImage } from '../specs/RiveImage.nitro';
+import type {
+  ReferencedAsset,
+  ReferencedAssets,
+  ResolvedReferencedAssets,
+} from '../core/ReferencedAssets';
+
+export type { ReferencedAssets, ResolvedReferencedAssets };
+export type RiveFileInput = number | { uri: string } | string | ArrayBuffer;
+
+export type UseRiveFileOptions = {
+  referencedAssets?: ReferencedAssets;
+};
+
+function isRiveImage(value: ReferencedAsset): value is RiveImage {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    '__type' in value &&
+    value.__type === 'HybridObject<RiveImage>'
+  );
+}
+
+function parsePossibleSources(asset: ReferencedAsset): ResolvedReferencedAsset {
+  if (isRiveImage(asset)) {
+    return { image: asset };
+  }
+
+  const source = asset.source;
+
+  if (typeof source === 'number') {
+    const resolvedAsset = Image.resolveAssetSource(source);
+    if (resolvedAsset && resolvedAsset.uri) {
+      return { sourceAssetId: resolvedAsset.uri };
+    } else {
+      throw new Error('Invalid asset source provided.');
+    }
+  }
+
+  const uri = (source as any).uri;
+  if (typeof source === 'object' && uri) {
+    return { sourceUrl: uri };
+  }
+
+  const fileName = (source as any).fileName;
+  const path = (source as any).path;
+
+  if (typeof source === 'object' && fileName) {
+    const result: ResolvedReferencedAsset = { sourceAsset: fileName };
+
+    if (path) {
+      result.path = path;
+    }
+
+    return result;
+  }
+
+  throw new Error('Invalid source provided.');
+}
+
+function transformFilesHandledMapping(
+  mapping?: ReferencedAssets
+): ResolvedReferencedAssets | undefined {
+  const transformedMapping: ResolvedReferencedAssets = {};
+  if (mapping === undefined) {
+    return undefined;
+  }
+
+  Object.entries(mapping).forEach(([key, asset]) => {
+    transformedMapping[key] = parsePossibleSources(asset);
+  });
+
+  return transformedMapping;
+}
+
+type RiveFileHookResult =
+  | { riveFile: RiveFile; isLoading: false; error: null }
+  | { riveFile: null; isLoading: true; error: null }
+  | { riveFile: null; isLoading: false; error: string };
+
+export function useRiveFile(
+  input: RiveFileInput | undefined,
+  options: UseRiveFileOptions = {}
+): RiveFileHookResult {
+  const [result, setResult] = useState<RiveFileHookResult>({
+    riveFile: null,
+    isLoading: true,
+    error: null,
+  });
+  const referencedAssets = useMemo(
+    () => transformFilesHandledMapping(options.referencedAssets),
+    [options.referencedAssets]
+  );
+  const initialReferencedAssets = useRef(referencedAssets);
+
+  useEffect(() => {
+    let currentFile: RiveFile | null = null;
+
+    const loadRiveFile = async () => {
+      try {
+        const currentInput = input;
+
+        if (currentInput == null) {
+          setResult({
+            riveFile: null,
+            isLoading: false,
+            error: 'No Rive file input provided.',
+          });
+          return;
+        }
+        if (typeof currentInput === 'string') {
+          if (
+            currentInput.startsWith('http://') ||
+            currentInput.startsWith('https://')
+          ) {
+            currentFile = await RiveFileFactory.fromURL(
+              currentInput,
+              initialReferencedAssets.current
+            );
+          } else {
+            currentFile = await RiveFileFactory.fromResource(
+              currentInput,
+              initialReferencedAssets.current
+            );
+          }
+        } else if (typeof currentInput === 'number' || 'uri' in currentInput) {
+          currentFile = await RiveFileFactory.fromSource(
+            currentInput,
+            initialReferencedAssets.current
+          );
+        } else if (currentInput instanceof ArrayBuffer) {
+          currentFile = await RiveFileFactory.fromBytes(
+            currentInput,
+            initialReferencedAssets.current
+          );
+        }
+
+        setResult({ riveFile: currentFile!, isLoading: false, error: null });
+      } catch (err) {
+        console.error(err);
+        setResult({
+          riveFile: null,
+          isLoading: false,
+          error:
+            err instanceof Error
+              ? err.message || 'Unknown error'
+              : 'Failed to load Rive file',
+        });
+      }
+    };
+
+    loadRiveFile();
+
+    return () => {
+      if (currentFile) {
+        callDispose(currentFile);
+      }
+    };
+  }, [input]);
+
+  const { riveFile } = result;
+  useEffect(() => {
+    if (initialReferencedAssets.current !== referencedAssets) {
+      if (riveFile && referencedAssets) {
+        riveFile.updateReferencedAssets({ data: referencedAssets });
+        initialReferencedAssets.current = referencedAssets;
+      }
+    }
+  }, [referencedAssets, riveFile]);
+
+  return {
+    riveFile: result.riveFile,
+    isLoading: result.isLoading,
+    error: result.error,
+  } as RiveFileHookResult;
+}

package/src/hooks/useRiveNumber.ts

@@ -0,0 +1,28 @@
+import {
+  type ViewModelInstance,
+  type ViewModelNumberProperty,
+} from '../specs/ViewModel.nitro';
+import type { UseRivePropertyResult } from '../types';
+import { useRiveProperty } from './useRiveProperty';
+
+const NUMBER_PROPERTY_OPTIONS = {
+  getProperty: (vmi: ViewModelInstance, p: string) => vmi.numberProperty(p),
+};
+
+/**
+ * Hook for interacting with number ViewModel instance properties.
+ *
+ * @param path - The path to the number property
+ * @param viewModelInstance - The ViewModelInstance containing the number property to operate on
+ * @returns An object with the number value, a setter function, and an error if the property is not found
+ */
+export function useRiveNumber(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRivePropertyResult<number> {
+  const [value, setValue, error] = useRiveProperty<
+    ViewModelNumberProperty,
+    number
+  >(viewModelInstance, path, NUMBER_PROPERTY_OPTIONS);
+  return { value, setValue, error };
+}

package/src/hooks/useRiveProperty.ts

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useState, useMemo } from 'react';
+import {
+  type ObservableProperty,
+  type ViewModelInstance,
+  type ViewModelProperty,
+} from '../specs/ViewModel.nitro';
+
+/**
+ * Base hook for all ViewModelInstance property interactions.
+ * This hook provides a unified interface for working with different types of
+ * Rive properties (boolean, number, string, enum, trigger) while maintaining
+ * type safety and proper cleanup.
+ *
+ * @template P - The type of the property (e.g., ViewModelBooleanProperty, ViewModelNumberProperty)
+ * @template T - The primitive type of the property value (number, boolean, string)
+ *
+ * @param viewModelInstance - The source ViewModelInstance
+ * @param path - Property path in the ViewModelInstance
+ * @param options - Configuration for working with the property
+ * @returns A tuple containing [value, setter, error, property]
+ */
+export function useRiveProperty<P extends ViewModelProperty, T>(
+  viewModelInstance: ViewModelInstance | null | undefined,
+  path: string,
+  options: {
+    /** Function to get the property from a ViewModelInstance */
+    getProperty: (vm: ViewModelInstance, path: string) => P | undefined;
+    /** Optional override callback for property events (mainly used by triggers) */
+    onPropertyEventOverride?: (...args: any[]) => void;
+  }
+): [T | undefined, (value: T) => void, Error | null, P | undefined] {
+  const [value, setValue] = useState<T | undefined>(undefined);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Clear error when path or instance changes
+  useEffect(() => {
+    setError(null);
+  }, [path, viewModelInstance]);
+
+  // Get the property
+  const property = useMemo(() => {
+    if (!viewModelInstance) return;
+    return options.getProperty(
+      viewModelInstance,
+      path
+    ) as unknown as ObservableViewModelProperty<T>;
+  }, [options, viewModelInstance, path]);
+
+  // Set error if property is not found
+  useEffect(() => {
+    if (viewModelInstance && !property) {
+      setError(
+        new Error(`Property "${path}" not found in the ViewModel instance`)
+      );
+    }
+  }, [viewModelInstance, property, path]);
+
+  // Add listener for changes to the property
+  useEffect(() => {
+    if (!property) return;
+
+    // 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);
+      });
+    }
+
+    // Cleanup: Remove listeners and dispose of the property
+    // This ensures proper cleanup of event listeners and resources
+    return () => {
+      property.removeListeners();
+      property.dispose();
+    };
+  }, [options, property]);
+
+  // Set the value of the property
+  const setPropertyValue = useCallback(
+    (newValue: T) => {
+      if (!property) {
+        setError(
+          new Error(
+            `Cannot set value for property "${path}" because it was not found. Your view model instance may be undefined, or the path may be incorrect.`
+          )
+        );
+      } else {
+        property.value = newValue;
+      }
+    },
+    [property, path]
+  );
+
+  return [value, setPropertyValue, error, property as unknown as P];
+}
+
+/**
+ * This interface extends the ViewModelProperty and ObservableProperty interfaces.
+ * It adds the addListener and value as known properties.
+ *
+ * @template T - The primitive type of the property value (number, boolean, string)
+ */
+interface ObservableViewModelProperty<T>
+  extends ViewModelProperty,
+    ObservableProperty {
+  addListener: (onChanged: (value: T) => void) => void;
+  value: T;
+}

package/src/hooks/useRiveString.ts

@@ -0,0 +1,28 @@
+import {
+  type ViewModelInstance,
+  type ViewModelStringProperty,
+} from '../specs/ViewModel.nitro';
+import type { UseRivePropertyResult } from '../types';
+import { useRiveProperty } from './useRiveProperty';
+
+const STRING_PROPERTY_OPTIONS = {
+  getProperty: (vmi: ViewModelInstance, p: string) => vmi.stringProperty(p),
+};
+
+/**
+ * Hook for interacting with string ViewModel instance properties.
+ *
+ * @param path - The path to the string property
+ * @param viewModelInstance - The ViewModelInstance containing the string property to operate on
+ * @returns An object with the number value, a setter function, and an error if the property is not found
+ */
+export function useRiveString(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRivePropertyResult<string> {
+  const [value, setValue, error] = useRiveProperty<
+    ViewModelStringProperty,
+    string
+  >(viewModelInstance, path, STRING_PROPERTY_OPTIONS);
+  return { value, setValue, error };
+}

package/src/hooks/useRiveTrigger.ts

@@ -0,0 +1,49 @@
+import { useCallback, useMemo } from 'react';
+import {
+  type ViewModelInstance,
+  type ViewModelTriggerProperty,
+} from '../specs/ViewModel.nitro';
+import type {
+  UseRiveTriggerResult,
+  UseViewModelInstanceTriggerParameters,
+} from '../types';
+import { useRiveProperty } from './useRiveProperty';
+
+const getTriggerProperty = (vmi: ViewModelInstance, p: string) =>
+  vmi.triggerProperty(p);
+
+/**
+ * Hook for interacting with trigger ViewModel instance properties.
+ *
+ * @param path - The path to the trigger property
+ * @param viewModelInstance - The ViewModelInstance containing the trigger property to operate on
+ * @returns A trigger function that can be called to fire the trigger
+ */
+export function useRiveTrigger(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null,
+  params?: UseViewModelInstanceTriggerParameters
+): UseRiveTriggerResult {
+  const { onTrigger } = params ?? {};
+
+  const triggerOptions = useMemo(
+    () => ({
+      getProperty: getTriggerProperty,
+      onPropertyEventOverride: onTrigger,
+    }),
+    [onTrigger]
+  );
+
+  const [_, __, error, property] = useRiveProperty<
+    ViewModelTriggerProperty,
+    undefined
+  >(viewModelInstance, path, triggerOptions);
+
+  const trigger = useCallback(() => {
+    if (property) {
+      property.trigger();
+    }
+  }, [property]);
+
+  return { trigger, error };
+}

package/src/index.tsx

@@ -0,0 +1,52 @@
+import { type HybridView } from 'react-native-nitro-modules';
+import {
+  type RiveViewMethods,
+  type RiveViewTSMethods,
+  type RiveViewProps as NativeRiveViewProps,
+  DataBindMode,
+  type DataBindByName as DataBindByNameInterface,
+} from './specs/RiveView.nitro';
+
+export class DataBindByName implements DataBindByNameInterface {
+  byName: string;
+  constructor(name: string) {
+    this.byName = name;
+  }
+}
+
+export { NitroRiveView } from './core/NitroRiveViewComponent';
+
+export { RiveView, type RiveViewProps } from './core/RiveView';
+export type { RiveViewMethods };
+export type RiveViewRef = HybridView<NativeRiveViewProps, RiveViewTSMethods>;
+export type { RiveFile } from './specs/RiveFile.nitro';
+export type {
+  ViewModel,
+  ViewModelInstance,
+  ViewModelNumberProperty,
+  ViewModelStringProperty,
+  ViewModelBooleanProperty,
+  ViewModelColorProperty,
+  ViewModelEnumProperty,
+  ViewModelTriggerProperty,
+  ViewModelImageProperty,
+} from './specs/ViewModel.nitro';
+export { Fit } from './core/Fit';
+export { Alignment } from './core/Alignment';
+export { RiveFileFactory } from './core/RiveFile';
+export { RiveImages } from './core/RiveImages';
+export type { RiveImage } from './specs/RiveImage.nitro';
+export { RiveColor } from './core/RiveColor';
+export { type RiveEvent, RiveEventType } from './core/Events';
+export { type RiveError, RiveErrorType } from './core/Errors';
+export { ArtboardByIndex, ArtboardByName } from './specs/ArtboardBy';
+export { useRive } from './hooks/useRive';
+export { useRiveNumber } from './hooks/useRiveNumber';
+export { useRiveString } from './hooks/useRiveString';
+export { useRiveBoolean } from './hooks/useRiveBoolean';
+export { useRiveEnum } from './hooks/useRiveEnum';
+export { useRiveColor } from './hooks/useRiveColor';
+export { useRiveTrigger } from './hooks/useRiveTrigger';
+export { useRiveFile } from './hooks/useRiveFile';
+export { type RiveFileInput } from './hooks/useRiveFile';
+export { DataBindMode };

package/src/specs/ArtboardBy.ts

@@ -0,0 +1,31 @@
+type ArtboardByTypes = 'index' | 'name';
+export interface ArtboardBy {
+  type: ArtboardByTypes;
+  index?: number;
+  name?: string;
+}
+
+/**
+ * Creates an ArtboardBy object for the artboard at the given index.
+ * @param {number} index - The index of the artboard to create an ArtboardBy object for.
+ * @returns {ArtboardBy} An ArtboardBy object for the artboard at the given index.
+ */
+export const ArtboardByIndex = (index: number): ArtboardBy => {
+  if (!Number.isInteger(index)) {
+    throw new Error('Artboard index must be an integer');
+  }
+  return {
+    type: 'index',
+    index: index,
+  };
+};
+
+/**
+ * Creates an ArtboardBy object for the artboard with the given name.
+ * @param {string} name - The name of the artboard to create an ArtboardBy object for.
+ * @returns {ArtboardBy} An ArtboardBy object for the artboard with the given name.
+ */
+export const ArtboardByName = (name: string): ArtboardBy => ({
+  type: 'name',
+  name: name,
+});

package/src/specs/Rive.nitro.ts

@@ -0,0 +1,6 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+export interface Rive
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  multiply(a: number, b: number): number;
+}