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

package/package.json

@@ -0,0 +1,193 @@
+{
+  "name": "@rive-app/react-native",
+  "version": "0.1.1-beta.0",
+  "description": "Rive React Native",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "nitrogen",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-rive-example",
+    "test": "jest",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "npx react-native-builder-bob@^0.40.0 build",
+    "nitrogen": "nitrogen",
+    "release": "release-it",
+    "dev:ios": "cd example && xed ios",
+    "dev:android": "cd example && open -a \"/Applications/Android Studio.app\" ./android",
+    "copy:nitrogen-config": "mkdir -p lib/nitrogen/generated/shared/json && cp nitrogen/generated/shared/json/RiveViewConfig.json lib/nitrogen/generated/shared/json/",
+    "lint:swift": "./scripts/lint-swift.sh",
+    "lint:kotlin": "./scripts/lint-kotlin.sh",
+    "lint:native": "yarn lint:swift && yarn lint:kotlin"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rive-app/rive-nitro-react-native.git"
+  },
+  "author": "Rive <support@rive.app> (https://rive.app)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/rive-app/rive-nitro-react-native/issues"
+  },
+  "homepage": "https://github.com/rive-app/rive-nitro-react-native#readme",
+  "runtimeVersions": {
+    "ios": "6.12.0",
+    "android": "10.5.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.6.0",
+    "@eslint/compat": "^1.2.7",
+    "@eslint/eslintrc": "^3.3.0",
+    "@eslint/js": "^9.22.0",
+    "@react-native/babel-preset": "0.79.2",
+    "@react-native/eslint-config": "^0.78.0",
+    "@release-it/conventional-changelog": "^9.0.2",
+    "@testing-library/react-hooks": "^8.0.1",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.5",
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.4",
+    "@typescript-eslint/parser": "^8.46.4",
+    "commitlint": "^19.6.1",
+    "del-cli": "^5.1.0",
+    "eslint": "^9.22.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-jest": "^29.1.0",
+    "eslint-plugin-prettier": "^5.2.3",
+    "jest": "^29.7.0",
+    "nitrogen": "0.31.10",
+    "prettier": "^3.0.3",
+    "react": "19.0.0",
+    "react-native": "0.79.2",
+    "react-native-builder-bob": "^0.40.10",
+    "react-native-nitro-modules": "0.31.10",
+    "react-test-renderer": "19.0.0",
+    "release-it": "^17.10.0",
+    "turbo": "^1.10.7",
+    "typescript": "^5.2.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": ">=0.31.8"
+  },
+  "workspaces": [
+    "example",
+    "expo-example"
+  ],
+  "packageManager": "yarn@3.6.1",
+  "jest": {
+    "preset": "react-native",
+    "setupFilesAfterEnv": [
+      "<rootDir>/jest-setup.js"
+    ],
+    "testMatch": [
+      "<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}",
+      "<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}"
+    ],
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ],
+    "moduleNameMapper": {
+      "^../nitrogen/generated/shared/json/RiveViewConfig\\.json$": "<rootDir>/jest-setup.js"
+    }
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ],
+      [
+        "custom",
+        {
+          "script": "copy:nitrogen-config",
+          "clean": "lib/nitrogen"
+        }
+      ]
+    ]
+  },
+  "create-react-native-library": {
+    "languages": "kotlin-swift",
+    "type": "nitro-module",
+    "version": "0.50.2"
+  }
+}

package/src/core/Alignment.ts

@@ -0,0 +1,46 @@
+export enum Alignment {
+  /**
+   * Aligns content to the top-left corner of the container
+   */
+  TopLeft = 'topLeft',
+
+  /**
+   * Centers content horizontally at the top of the container
+   */
+  TopCenter = 'topCenter',
+
+  /**
+   * Aligns content to the top-right corner of the container
+   */
+  TopRight = 'topRight',
+
+  /**
+   * Centers content vertically on the left side of the container
+   */
+  CenterLeft = 'centerLeft',
+
+  /**
+   * Centers content both horizontally and vertically in the container
+   */
+  Center = 'center',
+
+  /**
+   * Centers content vertically on the right side of the container
+   */
+  CenterRight = 'centerRight',
+
+  /**
+   * Aligns content to the bottom-left corner of the container
+   */
+  BottomLeft = 'bottomLeft',
+
+  /**
+   * Centers content horizontally at the bottom of the container
+   */
+  BottomCenter = 'bottomCenter',
+
+  /**
+   * Aligns content to the bottom-right corner of the container
+   */
+  BottomRight = 'bottomRight',
+}

package/src/core/Errors.ts

@@ -0,0 +1,14 @@
+export enum RiveErrorType {
+  Unknown = 0,
+  FileNotFound = 1,
+  MalformedFile = 2,
+  IncorrectArtboardName = 3,
+  IncorrectStateMachineName = 4,
+  ViewModelInstanceNotFound = 6,
+  IncorrectStateMachineInputName = 8,
+}
+
+export interface RiveError {
+  message: string;
+  type: RiveErrorType;
+}

package/src/core/Events.ts

@@ -0,0 +1,31 @@
+export enum RiveEventType {
+  General,
+  OpenUrl,
+}
+
+export type EventPropertiesOutput = number | boolean | string;
+
+export interface UnifiedRiveEvent {
+  name: string;
+  type: RiveEventType;
+  delay?: number;
+  properties?: Record<string, EventPropertiesOutput>;
+  url?: string;
+  target?: string;
+}
+
+export type RiveEvent = {
+  name: string;
+  delay?: number;
+  properties?: Record<string, EventPropertiesOutput>;
+  type: RiveEventType;
+} & (
+  | {
+      type: RiveEventType.General;
+    }
+  | {
+      type: RiveEventType.OpenUrl;
+      url?: string;
+      target?: string;
+    }
+);

package/src/core/Fit.ts

@@ -0,0 +1,54 @@
+export enum Fit {
+  /**
+   * Rive content will fill the available view. If the aspect ratios differ,
+   * then the Rive content will be stretched.
+   */
+  Fill,
+
+  /**
+   * Rive content will be contained within the view, preserving the aspect
+   * ratio. If the ratios differ, then a portion of the view will be unused
+   */
+  Contain,
+
+  /**
+   * Rive will cover the view, preserving the aspect ratio. If the Rive
+   * content has a different ratio to the view, then the Rive content will be
+   * clipped.
+   */
+  Cover,
+
+  /**
+   * Rive content will fill to the width of the view. This may result in
+   * clipping or unfilled view space.
+   */
+  FitWidth,
+
+  /**
+   * Rive content will fill to the height of the view. This may result in
+   * clipping or unfilled view space.
+   */
+  FitHeight,
+
+  /**
+   * Rive content will render to the size of its artboard, which may result
+   * in clipping or unfilled view space.
+   */
+  None,
+
+  /**
+   * Rive content is scaled down to the size of the view, preserving the
+   * aspect ratio. This is equivalent to Contain when the content is larger
+   * than the canvas. If the canvas is larger, then ScaleDown will not scale
+   * up.
+   */
+  ScaleDown,
+
+  /**
+   * Rive content will be resized automatically based on layout constraints of
+   * the artboard to match the underlying widget size.
+   *
+   * @see [Responsive Layout](https://rive.app/community/doc/layout/docBl81zd1GB#responsive-layout)
+   */
+  Layout,
+}

package/src/core/NitroRiveViewComponent.ts

@@ -0,0 +1,18 @@
+import {
+  getHostComponent,
+  type ReactNativeView,
+} from 'react-native-nitro-modules';
+import type {
+  RiveViewMethods,
+  RiveViewTSMethods,
+  RiveViewProps as NativeRiveViewProps,
+} from '../specs/RiveView.nitro';
+import RiveViewConfig from '../../nitrogen/generated/shared/json/RiveViewConfig.json';
+
+export const NitroRiveView = getHostComponent<
+  NativeRiveViewProps,
+  RiveViewMethods
+>('RiveView', () => RiveViewConfig) as ReactNativeView<
+  NativeRiveViewProps,
+  RiveViewTSMethods
+>;

package/src/core/ReferencedAssets.ts

@@ -0,0 +1,14 @@
+import type { ResolvedReferencedAsset } from '../specs/RiveFile.nitro';
+import type { RiveImage } from '../specs/RiveImage.nitro';
+
+export type ReferencedAssetSource = { source: number | { uri: string } };
+
+export type ReferencedAsset = ReferencedAssetSource | RiveImage;
+
+export interface ReferencedAssets {
+  [assetName: string]: ReferencedAsset;
+}
+
+export type ResolvedReferencedAssets = {
+  [assetName: string]: ResolvedReferencedAsset;
+};

package/src/core/RiveColor.ts

@@ -0,0 +1,100 @@
+/* eslint-disable no-bitwise */
+
+/**
+ * Represents a color in RGBA format for use with Rive color data binding.
+ * Each channel (r, g, b, a) is represented as a number between 0-255.
+ */
+export class RiveColor {
+  /**
+   * Creates a new RiveColor instance.
+   * @param r - Red channel (0-255)
+   * @param g - Green channel (0-255)
+   * @param b - Blue channel (0-255)
+   * @param a - Alpha channel (0-255, where 255 is fully opaque)
+   */
+  constructor(
+    public readonly r: number,
+    public readonly g: number,
+    public readonly b: number,
+    public readonly a: number
+  ) {}
+
+  /**
+   * Compares this color with another RiveColor instance.
+   * @param other - The RiveColor to compare with
+   * @returns true if the colors are equal, false otherwise
+   */
+  equals(other: RiveColor | undefined): boolean {
+    if (!other) return false;
+    return (
+      this.r === other.r &&
+      this.g === other.g &&
+      this.b === other.b &&
+      this.a === other.a
+    );
+  }
+
+  /**
+   * Creates a RiveColor instance from a hex color string.
+   * Supports both 6-digit (#RRGGBB) and 8-digit (#RRGGBBAA) formats.
+   * @param color - Hex color string (e.g., '#FF0000' or '#FF000080')
+   * @returns A new RiveColor instance
+   * @throws Will return black (0,0,0,255) with a warning if the hex string is invalid
+   */
+  static fromHexString(color: string): RiveColor {
+    const hex = color.replace(/^#/, '');
+
+    const isValidHex = /^[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/.test(hex);
+    if (!isValidHex) {
+      console.warn(`Rive invalid hex color: ${color}`);
+      return new RiveColor(0, 0, 0, 255);
+    }
+
+    let r = parseInt(hex.slice(0, 2), 16),
+      g = parseInt(hex.slice(2, 4), 16),
+      b = parseInt(hex.slice(4, 6), 16),
+      a = 255;
+
+    // Optionally parse alpha channel if present
+    if (hex.length === 8) {
+      a = parseInt(hex.slice(6, 8), 16);
+    }
+
+    return new RiveColor(r, g, b, a);
+  }
+
+  /**
+   * Creates a RiveColor instance from a 32-bit integer.
+   * The integer should be in ARGB format where:
+   * - Bits 24-31: Alpha channel
+   * - Bits 16-23: Red channel
+   * - Bits 8-15: Green channel
+   * - Bits 0-7: Blue channel
+   * @param colorValue - 32-bit integer representing the color
+   * @returns A new RiveColor instance
+   */
+  static fromInt(colorValue: number): RiveColor {
+    const a = (colorValue >> 24) & 0xff;
+    const r = (colorValue >> 16) & 0xff;
+    const g = (colorValue >> 8) & 0xff;
+    const b = colorValue & 0xff;
+    return new RiveColor(r, g, b, a);
+  }
+
+  /**
+   * Converts this color to a 32-bit integer in ARGB format.
+   * @returns A 32-bit integer where:
+   * - Bits 24-31: Alpha channel
+   * - Bits 16-23: Red channel
+   * - Bits 8-15: Green channel
+   * - Bits 0-7: Blue channel
+   */
+  toInt(): number {
+    return (
+      ((this.a & 0xff) << 24) |
+      ((this.r & 0xff) << 16) |
+      ((this.g & 0xff) << 8) |
+      (this.b & 0xff)
+    );
+  }
+}

package/src/core/RiveFile.ts

@@ -0,0 +1,149 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type {
+  RiveFile,
+  RiveFileFactory as RiveFileFactoryInternal,
+} from '../specs/RiveFile.nitro';
+
+import { Image } from 'react-native';
+import type { ResolvedReferencedAssets } from './ReferencedAssets';
+
+const RiveFileInternal =
+  NitroModules.createHybridObject<RiveFileFactoryInternal>('RiveFileFactory');
+
+/**
+ * Factory namespace for creating RiveFile instances from different sources.
+ * 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 (.riv) file
+   * @param loadCdn - Whether to load from CDN (default: true)
+   * @returns Promise that resolves to a RiveFile instance
+   */
+  export async function fromURL(
+    url: string,
+    referencedAssets: ResolvedReferencedAssets | undefined,
+    loadCdn: boolean = true
+  ): Promise<RiveFile> {
+    return RiveFileInternal.fromURL(
+      url,
+      loadCdn,
+      referencedAssets ? { data: referencedAssets } : undefined
+    );
+  }
+
+  /**
+   * Creates a RiveFile instance from a local file path URL.
+   * @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
+   */
+  export async function fromFileURL(
+    fileURL: string,
+    referencedAssets: ResolvedReferencedAssets | undefined = undefined,
+    loadCdn: boolean = true
+  ): Promise<RiveFile> {
+    return RiveFileInternal.fromFileURL(
+      fileURL,
+      loadCdn,
+      referencedAssets ? { data: referencedAssets } : undefined
+    );
+  }
+
+  /**
+   * Creates a RiveFile instance from a local resource.
+   * @param resource - The name of the local resource
+   * @param loadCdn - Whether to load from CDN (default: true)
+   * @returns Promise that resolves to a RiveFile instance
+   */
+  export async function fromResource(
+    resource: string,
+    referencedAssets: ResolvedReferencedAssets | undefined,
+    loadCdn: boolean = true
+  ): Promise<RiveFile> {
+    return RiveFileInternal.fromResource(
+      resource,
+      loadCdn,
+      referencedAssets ? { data: referencedAssets } : undefined
+    );
+  }
+
+  /**
+   * Creates a RiveFile instance from raw bytes.
+   * @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
+   */
+  export async function fromBytes(
+    bytes: ArrayBuffer,
+    referencedAssets: ResolvedReferencedAssets | undefined,
+    loadCdn: boolean = true
+  ): Promise<RiveFile> {
+    return RiveFileInternal.fromBytes(
+      bytes,
+      loadCdn,
+      referencedAssets ? { data: referencedAssets } : undefined
+    );
+  }
+
+  /**
+   * Creates a RiveFile instance from a source that can be either a resource ID or a URI object.
+   * @param source - Either a number representing a resource ID or an object with a uri property
+   * @param loadCdn - Whether to load from CDN (default: true)
+   * @returns Promise that resolves to a RiveFile instance
+   * @throws Error if the source is invalid or cannot be resolved
+   * @example
+   * // Using a resource ID
+   * const riveFile1 = await RiveFileFactory.fromSource(require('./your_file.riv'));
+   *
+   * // Using a URI object
+   * 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/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
+   * const config = getDefaultConfig(__dirname);
+   * config.resolver.assetExts = [...config.resolver.assetExts, 'riv'];
+   * ```
+   */
+  export async function fromSource(
+    source: number | { uri: string },
+    referencedAssets: ResolvedReferencedAssets | undefined,
+    loadCdn: boolean = true
+  ): Promise<RiveFile> {
+    const assetID = typeof source === 'number' ? source : null;
+    const sourceURI = typeof source === 'object' ? source.uri : null;
+
+    const assetURI = assetID
+      ? Image.resolveAssetSource(assetID)?.uri
+      : sourceURI;
+
+    if (!assetURI) {
+      throw new Error(
+        `Invalid source provided, ${source} is not a valid asset ID or URI`
+      );
+    }
+
+    try {
+      // handle http address and dev server
+      if (assetURI.match(/https?:\/\//)) {
+        return RiveFileFactory.fromURL(assetURI, referencedAssets, loadCdn);
+      }
+
+      // handle iOS bundled asset
+      if (assetURI.match(/file:\/\//)) {
+        return RiveFileFactory.fromFileURL(assetURI, referencedAssets, loadCdn);
+      }
+
+      // handle Android bundled asset or resource name uri
+      return RiveFileFactory.fromResource(assetURI, referencedAssets, loadCdn);
+    } catch (error: unknown) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to load Rive file from source: ${errorMessage}`);
+    }
+  }
+}

package/src/core/RiveImages.ts

@@ -0,0 +1,5 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { RiveImageFactory } from '../specs/RiveImage.nitro';
+
+export const RiveImages =
+  NitroModules.createHybridObject<RiveImageFactory>('RiveImageFactory');

package/src/core/RiveView.tsx

@@ -0,0 +1,48 @@
+import type { ComponentProps } from 'react';
+import { NitroRiveView } from './NitroRiveViewComponent';
+import { RiveErrorType, type RiveError } from './Errors';
+
+export interface RiveViewProps
+  extends Omit<ComponentProps<typeof NitroRiveView>, 'onError'> {
+  onError?: (error: RiveError) => void;
+}
+
+const defaultOnError = (error: RiveError) =>
+  console.error(`[${RiveErrorType[error.type]}] ${error.message}`);
+
+/**
+ * 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
+ * ```tsx
+ * <RiveView
+ *   file={riveFile}
+ *   artboardName="New Artboard"
+ *   stateMachineName="State Machine 1"
+ *   autoPlay={true}
+ *   fit={Fit.Contain}
+ *   style={styles.riveContainer}
+ * />
+ * ```
+ *
+ * @property {RiveFile} file - The Rive file to be displayed
+ * @property {string} [artboardName] - Name of the artboard to display from the Rive file
+ * @property {string} [stateMachineName] - Name of the state machine to play
+ * @property {ViewModelInstance | DataBindMode | DataBindByName} [dataBind] - Data binding configuration for the state machine, defaults to DataBindMode.Auto
+ * @property {boolean} [autoPlay=true] - Whether to automatically start playing the state machine
+ * @property {Alignment} [alignment] - How the Rive graphic should be aligned within its container
+ * @property {Fit} [fit] - How the Rive graphic should fit within its container
+ * @property {Object} [style] - React Native style object for container customization
+ * @property {(error: RiveError) => void} [onError] - Callback function that is called when an error occurs
+ *
+ * The component also exposes methods for controlling playback:
+ * - play(): Starts playing the Rive graphic
+ * - pause(): Pauses the Rive graphic
+ */
+export function RiveView(props: RiveViewProps) {
+  const { onError, ...rest } = props;
+  const wrappedOnError = onError ?? defaultOnError;
+
+  return <NitroRiveView {...rest} onError={{ f: wrappedOnError }} />;
+}