feat: add useViewModelInstanceArtboard hook

src/hooks/useViewModelInstanceArtboard.ts

@@ -0,0 +1,35 @@
+import { useCallback } from 'react';
+import { ViewModelInstance, ViewModelInstanceArtboard } from '@rive-app/canvas';
+import { UseViewModelInstanceArtboardResult } from '../types';
+import { useViewModelInstanceProperty } from './useViewModelInstanceProperty';
+
+/**
+ * Hook for interacting with artboard properties of a ViewModelInstance.
+ *
+ * @param path - Path to the artboard property (e.g. "targetArtboard" or "group/artboard")
+ * @param viewModelInstance - The ViewModelInstance containing the artboard property
+ * @returns An object with a setter function
+ */
+export default function useViewModelInstanceArtboard(
+    path: string,
+    viewModelInstance?: ViewModelInstance | null
+): UseViewModelInstanceArtboardResult {
+    const result = useViewModelInstanceProperty<ViewModelInstanceArtboard, undefined, UseViewModelInstanceArtboardResult>(
+        path,
+        viewModelInstance,
+        {
+            getProperty: useCallback((vm, p) => vm.artboard(p), []),
+            getValue: useCallback(() => undefined, []), // Artboards properties don't currently have a readable value
+            defaultValue: null,
+            buildPropertyOperations: useCallback((safePropertyAccess) => ({
+                setValue: (newValue) => {
+                    safePropertyAccess(prop => { prop.value = newValue; });
+                }
+            }), [])
+        }
+    );
+
+    return {
+        setValue: result.setValue
+    };
+}

src/index.ts

@@ -13,6 +13,7 @@ import useViewModelInstanceImage from './hooks/useViewModelInstanceImage';
 import useViewModelInstanceList from './hooks/useViewModelInstanceList';
 import useResizeCanvas from './hooks/useResizeCanvas';
 import useRiveFile from './hooks/useRiveFile';
+import useViewModelInstanceArtboard from './hooks/useViewModelInstanceArtboard';
 
 export default Rive;
 export {
@@ -30,6 +31,7 @@ export {
     useViewModelInstanceTrigger,
     useViewModelInstanceImage,
     useViewModelInstanceList,
+    useViewModelInstanceArtboard,
     RiveProps,
 };
 export {

src/types.ts

@@ -5,6 +5,7 @@ import {
   RiveFileParameters,
   RiveParameters,
   ViewModelInstance,
+  ViewModelInstanceArtboard,
 } from '@rive-app/canvas';
 import { ComponentProps, RefCallback } from 'react';
 
@@ -238,4 +239,12 @@ export type UseViewModelInstanceListResult = {
    * @param b - The second index.
    */
   swap: (a: number, b: number) => void;
+};
+
+export type UseViewModelInstanceArtboardResult = {
+  /**
+   * Set the value of the artboard.
+   * @param value - The artboard to set.
+   */
+  setValue: (value: ViewModelInstanceArtboard extends { value: infer T } ? T : never) => void;
 };