From 5c5ba945bad72056c88e559840062adc392e63c0 Mon Sep 17 00:00:00 2001
From: Jonny Burger <jonathanburger11@gmail.com>
Date: Wed, 10 Jul 2024 09:26:58 +0200
Subject: [PATCH] `@remotion/rive`: Add `ref` option for `<RemotionRiveCanvas>`

---
 .../docs/docs/rive/remotionrivecanvas.mdx     | 79 +++++++++++++++----
 packages/rive/src/RemotionRiveCanvas.tsx      | 12 +--
 packages/rive/src/index.ts                    |  2 +-
 3 files changed, 71 insertions(+), 22 deletions(-)

diff --git a/packages/docs/docs/rive/remotionrivecanvas.mdx b/packages/docs/docs/rive/remotionrivecanvas.mdx
index 784e717f052..57fc906ccd0 100644
--- a/packages/docs/docs/rive/remotionrivecanvas.mdx
+++ b/packages/docs/docs/rive/remotionrivecanvas.mdx
@@ -1,14 +1,24 @@
 ---
 image: /generated/articles-docs-rive-remotionrivecanvas.png
-crumb: "@remotion/rive"
-sidebar_label: "<RemotionRiveCanvas>"
-title: "<RemotionRiveCanvas>"
+crumb: '@remotion/rive'
+sidebar_label: '<RemotionRiveCanvas>'
+title: '<RemotionRiveCanvas>'
 ---
 
-<AvailableFrom v="3.3.75"/>
+# &lt;RemotionRiveCanvas&gt;<AvailableFrom v="3.3.75"/>
 
 This component can render a [Rive](https://rive.app/) animation so it synchronizes with Remotion's time.
 
+## Example
+
+```tsx twoslash
+import {RemotionRiveCanvas} from '@remotion/rive';
+
+function App() {
+  return <RemotionRiveCanvas src="https://example.com/myAnimation.riv" />;
+}
+```
+
 ## Props
 
 ### `src`
@@ -35,31 +45,70 @@ Either a `string` specifying the animation name, a `number` specifying the anima
 
 A callback function that will be executed when the Rive Runtime is loaded. The argument callback is an object of type Rive `File`
 
-## Basic Example
+## Ref<AvailableFrom v="4.0.180" />
 
-```tsx twoslash
-import { RemotionRiveCanvas } from "@remotion/rive";
+You can attach a ref to the component to access the Rive Canvas instance.
 
-function App() {
-  return <RemotionRiveCanvas src="https://example.com/myAnimation.riv" />;
-}
+```tsx twoslash title="MyComp.tsx"
+import {RemotionRiveCanvas, RiveCanvasRef} from '@remotion/rive';
+import {useEffect} from 'react';
+
+const MyComp: React.FC = () => {
+  const canvasRef = React.useRef<RiveCanvasRef>(null);
+
+  useEffect(() => {
+    if (!canvasRef.current) {
+      return;
+    }
+
+    canvasRef.current.getAnimationInstance(); // import("@rive-app/canvas-advanced").LinearAnimationInstance
+    canvasRef.current.getArtboard(); // import("@rive-app/canvas-advanced").Artboard
+    canvasRef.current.getRenderer(); // import("@rive-app/canvas-advanced").CanvasRenderer
+    canvasRef.current.getCanvas(); // import("@rive-app/canvas-advanced").RiveCanvas
+  }, [canvasRef]);
+
+  return (
+    <RemotionRiveCanvas
+      src="https://example.com/myAnimation.riv"
+      ref={canvasRef}
+    />
+  );
+};
 ```
 
+The ref exposes the following methods:
+
+### `getAnimationInstance()`
+
+Returns a [`LinearAnimationInstance`](https://github.com/rive-app/rive-wasm/blob/caacb99a5b503d3fa56e8e921af2a7015478851c/js/src/rive_advanced.mjs.d.ts#L513) from the Rive Runtime.
+
+### `getArtboard()`
+
+Returns a [`Artboard`](https://github.com/rive-app/rive-wasm/blob/caacb99a5b503d3fa56e8e921af2a7015478851c/js/src/rive_advanced.mjs.d.ts) from the Rive Runtime.
+
+### `getRenderer()`
+
+Returns a [`CanvasRenderer`](https://github.com/rive-app/rive-wasm/blob/caacb99a5b503d3fa56e8e921af2a7015478851c/js/src/rive_advanced.mjs.d.ts#L221) from the Rive Runtime.
+
+### `getCanvas()`
+
+Returns a [`RiveCanvas`](https://github.com/rive-app/rive-wasm/blob/caacb99a5b503d3fa56e8e921af2a7015478851c/js/src/rive_advanced.mjs.d.ts#L14) from the Rive Runtime.
+
 ## Set Text Run at Runtime Example
 
 This example assumes that your Rive animation has a text run named "city". See [here](https://help.rive.app/runtimes/text#low-level-api-usage) for
 more information about Text Runs on Rive.
 
 ```tsx twoslash
-import { RemotionRiveCanvas } from "@remotion/rive";
-import { File } from "@rive-app/canvas-advanced";
-import { useCallback } from "react";
+import {RemotionRiveCanvas} from '@remotion/rive';
+import {File} from '@rive-app/canvas-advanced';
+import {useCallback} from 'react';
 
 // Make sure to wrap your onLoad handler on `useCallback` to avoid re-rendering this component every single time
 const onLoadHandler = useCallback((file: File) => {
   const artboard = file.defaultArtboard();
-  const textRun = artboard.textRun("city");
-  textRun.text = "Tokyo";
+  const textRun = artboard.textRun('city');
+  textRun.text = 'Tokyo';
 }, []);
 
 function App() {
diff --git a/packages/rive/src/RemotionRiveCanvas.tsx b/packages/rive/src/RemotionRiveCanvas.tsx
index b9979a0488e..c3441631e08 100644
--- a/packages/rive/src/RemotionRiveCanvas.tsx
+++ b/packages/rive/src/RemotionRiveCanvas.tsx
@@ -29,12 +29,12 @@ import {mapToAlignment, mapToFit} from './map-enums.js';
 type onLoadCallback = (file: File) => void;
 
 interface RiveProps {
-	src: string;
-	fit?: RemotionRiveCanvasFit;
-	alignment?: RemotionRiveCanvasAlignment;
-	artboard?: string | number;
-	animation?: string | number;
-	onLoad?: onLoadCallback | null;
+	readonly src: string;
+	readonly fit?: RemotionRiveCanvasFit;
+	readonly alignment?: RemotionRiveCanvasAlignment;
+	readonly artboard?: string | number;
+	readonly animation?: string | number;
+	readonly onLoad?: onLoadCallback | null;
 }
 
 export type RiveCanvasRef = {
diff --git a/packages/rive/src/index.ts b/packages/rive/src/index.ts
index 2f62401fcf9..d43a798929c 100644
--- a/packages/rive/src/index.ts
+++ b/packages/rive/src/index.ts
@@ -1 +1 @@
-export {RemotionRiveCanvas} from './RemotionRiveCanvas.js';
+export {RemotionRiveCanvas, RiveCanvasRef} from './RemotionRiveCanvas.js';