From 963ecc43b80e6465d159621d014b70b8cbfee9d4 Mon Sep 17 00:00:00 2001
From: Adam <67035612+damzobridge@users.noreply.github.com>
Date: Thu, 10 Jul 2025 16:06:19 -0700
Subject: [PATCH] feat: add useViewModelInstanceArtboard hook

---
 src/hooks/useViewModelInstanceArtboard.ts | 35 +++++++++++++++++++++++
 src/index.ts                              |  2 ++
 src/types.ts                              |  9 ++++++
 3 files changed, 46 insertions(+)
 create mode 100644 src/hooks/useViewModelInstanceArtboard.ts

diff --git a/src/hooks/useViewModelInstanceArtboard.ts b/src/hooks/useViewModelInstanceArtboard.ts
new file mode 100644
index 0000000..f6ced0a
--- /dev/null
+++ b/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
+    };
+}
\ No newline at end of file
diff --git a/src/index.ts b/src/index.ts
index a9951e5..b4b6199 100644
--- a/src/index.ts
+++ b/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 {
diff --git a/src/types.ts b/src/types.ts
index 0493f5e..e9d983b 100644
--- a/src/types.ts
+++ b/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;
 };
\ No newline at end of file