chore: add responsive layout example and updated docs (#34)

* chore: add responsive layout example

* chore: rename example export to OutOfBandAssetsExample

* docs: expand error handling

Author: HayesGordon

README.md

@@ -116,7 +116,7 @@ export default {
 
 ## Error Handling
 
-All Rive operations can be wrapped in try/catch blocks for error handling:
+All Rive operations can be wrapped in try/catch blocks for error handling, for example, loading a file:
 
 ```js
 try {
@@ -125,11 +125,72 @@ try {
   );
   // Use the riveFile...
 } catch (error) {
-  // Handle any errors that occur during Rive operations
+  // Handle any errors that occur during Rive file loading
   console.error('Error loading Rive file:', error);
 }
 ```
 
+### View-Based Errors
+
+The `RiveView` component provides an `onError` callback prop to handle errors that occur during view configuration or runtime operations:
+
+```js
+<RiveView
+  file={riveFile}
+  onError={(error) => {
+    // error.type contains the error type enum value
+    // error.message contains a descriptive error message
+    console.error(`Rive Error [${error.type}]: ${error.message}`);
+  }}
+/>
+```
+
+#### Error Types
+
+The following error types can occur during view operations:
+
+| Error Type                                     | Value | Description                                           |
+| ---------------------------------------------- | ----- | ----------------------------------------------------- |
+| `RiveErrorType.Unknown`                        | 0     | An unknown error occurred                             |
+| `RiveErrorType.FileNotFound`                   | 1     | The specified Rive file could not be found            |
+| `RiveErrorType.MalformedFile`                  | 2     | The Rive file is malformed or corrupted               |
+| `RiveErrorType.IncorrectArtboardName`          | 3     | The specified artboard name does not exist            |
+| `RiveErrorType.IncorrectStateMachineName`      | 4     | The specified state machine name does not exist       |
+| `RiveErrorType.ViewModelInstanceNotFound`      | 6     | The specified view model instance was not found       |
+| `RiveErrorType.IncorrectStateMachineInputName` | 8     | The specified state machine input name does not exist |
+
+You can use these error types to provide specific error handling:
+
+```js
+import { RiveView, RiveErrorType } from 'react-native-rive';
+
+<RiveView
+  file={riveFile}
+  artboardName="MainArtboard"
+  onError={(error) => {
+    switch (error.type) {
+      case RiveErrorType.IncorrectArtboardName:
+        console.error('Artboard not found:', error.message);
+        // Handle missing artboard (e.g., use default artboard)
+        break;
+      case RiveErrorType.IncorrectStateMachineName:
+        console.error('State machine not found:', error.message);
+        // Handle missing state machine
+        break;
+      case RiveErrorType.MalformedFile:
+        console.error('Corrupted file:', error.message);
+        // Handle corrupted file (e.g., show error UI)
+        break;
+      default:
+        console.error('Rive error:', error.message);
+    }
+  }}
+  style={{ width: '100%', height: 400 }}
+/>;
+```
+
+> **Note**: If no `onError` handler is provided, errors will be logged to the console by default.
+
 ## Feature Support
 
 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.

example/assets/rive/layouts_demo.riv

@@ -14,7 +14,7 @@ import {
 import { Picker } from '@react-native-picker/picker';
 import { type Metadata } from '../helpers/metadata';
 
-export default function StateMachine() {
+export default function OutOfBandAssetsExample() {
   const [uri, setUri] = React.useState('https://picsum.photos/id/372/500/500');
   const { riveFile, isLoading, error } = useRiveFile(
     require('../../assets/rive/out_of_band.riv'),
@@ -143,7 +143,7 @@ const styles = StyleSheet.create({
   },
 });
 
-StateMachine.metadata = {
+OutOfBandAssetsExample.metadata = {
   name: 'Out-of-Band Assets',
   description:
     'Shows how to load referenced assets like fonts and images that are not embedded in the Rive file',

example/src/pages/OutOfBandAssets.tsx

@@ -0,0 +1,55 @@
+import { View, Text, StyleSheet, ActivityIndicator } from 'react-native';
+import { Fit, RiveView, useRiveFile } from 'react-native-rive';
+import { type Metadata } from '../helpers/metadata';
+
+/**
+ * Demonstrates responsive layouts using Fit.Layout and layoutScaleFactor
+ *
+ * See https://rive.app/docs/runtimes/layout
+ */
+export default function ResponsiveLayoutsExample() {
+  const { riveFile, isLoading, error } = useRiveFile(
+    require('../../assets/rive/layouts_demo.riv')
+  );
+
+  return (
+    <View style={styles.container}>
+      {isLoading ? (
+        <ActivityIndicator size="large" color="#0000ff" />
+      ) : error ? (
+        <Text style={styles.errorText}>{error}</Text>
+      ) : riveFile ? (
+        <RiveView
+          file={riveFile}
+          fit={Fit.Layout}
+          layoutScaleFactor={1} // adjust the layout scale factor to control the layout scale
+          style={styles.rive}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Adjust the container size and the layout will adjust based on the .riv file layout rules
+  container: {
+    width: '100%',
+    height: '100%',
+  },
+  rive: {
+    justifyContent: 'center',
+    alignItems: 'center',
+    width: '100%',
+    height: '100%',
+  },
+  errorText: {
+    color: 'red',
+    textAlign: 'center',
+    padding: 20,
+  },
+});
+
+ResponsiveLayoutsExample.metadata = {
+  name: 'Responsive Layouts',
+  description: 'Sample .riv file with responsive layouts',
+} satisfies Metadata;

example/src/pages/ResponsiveLayouts.tsx

@@ -6,3 +6,4 @@ export { default as StateMachineInputsExample } from './RiveStateMachineInputsEx
 export { default as TextRunExample } from './RiveTextRunExample';
 export { default as OutOfBandAssets } from './OutOfBandAssets';
 export { default as ManyViewModels } from './ManyViewModels';
+export { default as ResponsiveLayouts } from './ResponsiveLayouts';