docs: prefer term graphic over animation and update roadmap docs (#27)

* chore: prefer term graphic over animation

* docs: add deprecated warning

* docs: not on dev preview and updated roadmap

Author: HayesGordon

README.md

@@ -2,6 +2,10 @@
 
 Rive React Native 2.0
 
+## Development Preview
+
+> **⚠️ Development Preview**: This package is currently in development preview. While it's functional and actively maintained, the API may change in future releases. We recommend testing thoroughly before using in production applications. We're actively gathering feedback to improve the library. Please share your thoughts and report any issues you encounter.
+
 ## Requirements
 
 - **React Native**: 0.78 or later (0.79+ recommended for better Android error messages)
@@ -79,7 +83,10 @@ Rive_RiveRuntimeAndroidVersion=10.6.0
 Use an inline config plugin in your `app.config.ts`:
 
 ```typescript
-import { withPodfileProperties, withGradleProperties } from '@expo/config-plugins';
+import {
+  withPodfileProperties,
+  withGradleProperties,
+} from '@expo/config-plugins';
 
 export default {
   expo: {
@@ -125,32 +132,51 @@ try {
 
 ## Feature Support
 
-The following runtime features are currently supported:
-
-✅ Supported | ⚠️ Partial | 🚧 In Development | ❌ Not Planned
-
-| Feature                    | Status | Description                                                      |
-| -------------------------- | ------ | ---------------------------------------------------------------- |
-| Artboard selection         | ✅     | Sepecify artboard to render                                      |
-| State machine selection    | ✅     | Specify a state machine to play                                  |
-| Animation selection        | ❌     | Animation playback not planned, use state machines               |
-| View autoPlay & play/pause | ✅     | Control view playback                                            |
-| Fit & Alignment            | ✅     | Fit modes supported, alignment coming soon                       |
-| Layout & Responsiveness    | ✅     | Basic responsive layouts supported                               |
-| Data Binding               | ⚠️     | Control data binding through runtime code                        |
-| Asset management           | 🚧     | Out-of-band assets not yet supported                             |
-| State machine inputs       | ✅     | Get/Set (nested) state machine inputs (legacy, see data binding) |
-| Text Runs                  | ✅     | Update (nested) text runs (legacy, see data binding)             |
-| Rive Events                | ✅     | Listen to Rive events                                            |
-| Rive Audio                 | ✅     | Full Rive audio playback supported                               |
-| `useRive()` hook           | ✅     | Convenient hook to access the Rive View ref after load           |
-| `useRiveFile()` hook       | ✅     | Convenient hook to load a Rive file                              |
-| `RiveView` error handling  | ✅     | Error handler for failed view operations                         |
-| `source` .riv file loading | ✅     | Conveniently load .riv files from JS source                      |
-| Renderer options           | ❌     | Single renderer option available (Rive)                          |
+This section provides a comprehensive overview of feature availability in `react-native-rive`, comparing it with the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native) and outlining the development roadmap.
+
+### Runtime Feature Comparison
+
+**Status Legend:** ✅ Supported | ⚠️ Partial | 🚧 In Development | ❌ Not Planned
+
+The following table compares feature availability with the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native).
+
+| Feature                           | Status | Description                                                      |
+| --------------------------------- | ------ | ---------------------------------------------------------------- |
+| Artboard selection                | ✅     | Specify artboard to render                                       |
+| State machine selection           | ✅     | Specify a state machine to play                                  |
+| View autoPlay & play/pause        | ✅     | Control view playback                                            |
+| Fit & Alignment                   | ✅     | Fit modes supported, alignment coming soon                       |
+| Layout & Responsiveness           | ✅     | Basic responsive layouts supported                               |
+| Data Binding                      | ✅     | Control data binding through runtime code                        |
+| Asset management                  | ✅     | Load assets out of band (referenced)                             |
+| State machine inputs (Deprecated) | ✅     | Get/Set (nested) state machine inputs (legacy, see data binding) |
+| Text Runs (Deprecated)            | ✅     | Update (nested) text runs (legacy, see data binding)             |
+| Rive Events (Deprecated)          | ✅     | Listen to Rive events                                            |
+| Rive Audio                        | ✅     | Rive audio playback supported                                    |
+| `useRive()` hook                  | ✅     | Convenient hook to access the Rive View ref after load           |
+| `useRiveFile()` hook              | ✅     | Convenient hook to load a Rive file                              |
+| `RiveView` error handling         | ✅     | Error handler for failed view operations                         |
+| `source` .riv file loading        | ✅     | Conveniently load .riv files from JS source                      |
+| Animation selection               | ❌     | Animation playback not planned, use state machines               |
+| Renderer options                  | ❌     | Single renderer option available (Rive)                          |
 
 > **Note**: Several features in the table above (state machine inputs, text runs, and events) represent legacy approaches to runtime control. We recommend using data binding instead, as it provides a more maintainable way to control your Rive graphics (both at edit time and runtime).
 
+### Roadmap
+
+**Status Legend:** ✅ Completed | 🚧 Planned |
+
+This section tracks new features and improvements planned for this runtime that were not available in the [previous Rive React Native runtime](https://github.com/rive-app/rive-react-native).
+
+| Feature                                                                                               | Status |
+| ----------------------------------------------------------------------------------------------------- | ------ |
+| [Reusable .riv File resources (preloading)](https://github.com/rive-app/rive-react-native/issues/260) | ✅     |
+| [Data Binding - Images](https://github.com/rive-app/rive-nitro-react-native/issues/9)                 | 🚧     |
+| [Data Binding - Artboards](https://github.com/rive-app/rive-nitro-react-native/issues/10)             | 🚧     |
+| [Data Binding - Lists](https://github.com/rive-app/rive-nitro-react-native/issues/11)                 | 🚧     |
+| [Data Binding - Value props](https://github.com/rive-app/rive-nitro-react-native/pull/24)             | 🚧     |
+| [Suspense](https://github.com/rive-app/rive-nitro-react-native/pull/19)                               | 🚧     |
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

example/src/pages/OutOfBandAssets.tsx

@@ -63,7 +63,7 @@ export default function StateMachine() {
       <RiveView
         file={riveFile}
         fit={Fit.Contain}
-        style={styles.animation}
+        style={styles.rive}
         stateMachineName="State Machine 1"
         // The `referencedAssets` prop allows you to load external assets from various sources:
         // - A URI
@@ -122,7 +122,7 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'flex-start',
   },
-  animation: {
+  rive: {
     width: '100%',
     height: 400,
   },

example/src/pages/RiveEventsExample.tsx

@@ -10,6 +10,13 @@ import {
 } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Rive events at runtime is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and handling Rive events
+ */
 export default function EventsExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(

example/src/pages/RiveStateMachineInputsExample.tsx

@@ -3,6 +3,13 @@ import { useEffect } from 'react';
 import { Fit, RiveView, useRive, useRiveFile } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Setting state machine inputs at runtime is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and setting state machine inputs programmatically
+ */
 export default function StateMachineInputsExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(

example/src/pages/RiveTextRunExample.tsx

@@ -3,6 +3,13 @@ import { useEffect } from 'react';
 import { Fit, RiveView, useRive, useRiveFile } from 'react-native-rive';
 import { type Metadata } from '../helpers/metadata';
 
+/**
+ * @deprecated Setting text run values is deprecated. Use data binding instead.
+ *
+ * See https://rive.app/docs/runtimes/data-binding
+ *
+ * Demonstrates getting and setting text run values in Rive graphics
+ */
 export default function TextRunExample() {
   const { riveViewRef, setHybridRef } = useRive();
   const { riveFile, isLoading, error } = useRiveFile(
@@ -83,5 +90,5 @@ const styles = StyleSheet.create({
 TextRunExample.metadata = {
   name: 'Text Run',
   description:
-    'Demonstrates getting and setting text run values in Rive animations',
+    'Demonstrates getting and setting text run values in Rive graphics',
 } satisfies Metadata;

src/core/RiveFile.ts

@@ -14,12 +14,12 @@ const RiveFileInternal =
 
 /**
  * Factory namespace for creating RiveFile instances from different sources.
- * Provides static methods to load Rive animations from URLs, resources, or raw bytes.
+ * Provides static methods to load Rive files from URLs, resources, or raw bytes.
  */
 export namespace RiveFileFactory {
   /**
    * Creates a RiveFile instance from a URL.
-   * @param url - The URL of the Rive animation file
+   * @param url - The URL of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -37,7 +37,7 @@ export namespace RiveFileFactory {
 
   /**
    * Creates a RiveFile instance from a local file path URL.
-   * @param pathURL - The local file path of the Rive animation file
+   * @param pathURL - The local file path of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -73,7 +73,7 @@ export namespace RiveFileFactory {
 
   /**
    * Creates a RiveFile instance from raw bytes.
-   * @param bytes - The raw bytes of the Rive animation file
+   * @param bytes - The raw bytes of the Rive (.riv) file
    * @param loadCdn - Whether to load from CDN (default: true)
    * @returns Promise that resolves to a RiveFile instance
    */
@@ -97,13 +97,13 @@ export namespace RiveFileFactory {
    * @throws Error if the source is invalid or cannot be resolved
    * @example
    * // Using a resource ID
-   * const riveFile1 = await RiveFileFactory.fromSource(require('./animation.riv'));
+   * const riveFile1 = await RiveFileFactory.fromSource(require('./your_file.riv'));
    *
    * // Using a URI object
-   * const riveFile2 = await RiveFileFactory.fromSource({ uri: 'https://example.com/animation.riv' });
+   * const riveFile2 = await RiveFileFactory.fromSource({ uri: 'https://example.com/your_file.riv' });
    *
    * // Using a local file URI
-   * const riveFile3 = await RiveFileFactory.fromSource({ uri: 'file:///path/to/animation.riv' });
+   * const riveFile3 = await RiveFileFactory.fromSource({ uri: 'file:///path/to/your_file.riv' });
    *
    * @note To use .riv files with require(), you need to add 'riv' to the asset extensions in your metro.config.js:
    * ```js

src/index.tsx

@@ -28,7 +28,7 @@ export function multiply(a: number, b: number): number {
 }
 
 /**
- * RiveView is a React Native component that renders Rive animations.
+ * RiveView is a React Native component that renders Rive graphics.
  * It provides a seamless way to display and control Rive graphics in your app.
  *
  * @example
@@ -53,8 +53,8 @@ export function multiply(a: number, b: number): number {
  * @property {Object} [style] - React Native style object for container customization
  *
  * The component also exposes methods for controlling playback:
- * - play(): Starts playing the animation
- * - pause(): Pauses the animation
+ * - play(): Starts playing the Rive graphic
+ * - pause(): Pauses the Rive graphic
  */
 export const RiveView = getHostComponent<RiveViewProps, RiveViewMethods>(
   'RiveView',