feat: add functional updater support to setValue in property hooks

Author: mfazekas

src/hooks/useRiveColor.ts

@@ -3,14 +3,24 @@ import type {
   ViewModelColorProperty,
   ViewModelInstance,
 } from '../specs/ViewModel.nitro';
-import { type UseRivePropertyResult } from '../types';
 import { useRiveProperty } from './useRiveProperty';
 import { RiveColor } from '../core/RiveColor';
 
 const COLOR_PROPERTY_OPTIONS = {
   getProperty: (vmi: ViewModelInstance, p: string) => vmi.colorProperty(p),
 };
 
+type ColorInput = RiveColor | string;
+type ColorSetValueAction =
+  | ColorInput
+  | ((prevValue: RiveColor | undefined) => ColorInput);
+
+export interface UseRiveColorResult {
+  value: RiveColor | undefined;
+  setValue: (value: ColorSetValueAction) => void;
+  error: Error | null;
+}
+
 /**
  * Hook for interacting with color ViewModel instance properties.
  *
@@ -21,9 +31,7 @@ const COLOR_PROPERTY_OPTIONS = {
 export function useRiveColor(
   path: string,
   viewModelInstance?: ViewModelInstance | null
-): UseRivePropertyResult<RiveColor> & {
-  setValue: (value: RiveColor | string) => void;
-} {
+): UseRiveColorResult {
   const [rawValue, setRawValue, error] = useRiveProperty<
     ViewModelColorProperty,
     number
@@ -33,12 +41,20 @@ export function useRiveColor(
     rawValue !== undefined ? RiveColor.fromInt(rawValue) : undefined;
 
   const setValue = useCallback(
-    (newValue: RiveColor | string) => {
-      const color =
-        typeof newValue === 'string'
-          ? RiveColor.fromHexString(newValue)
-          : newValue;
-      setRawValue(color.toInt());
+    (valueOrUpdater: ColorSetValueAction) => {
+      setRawValue((prevRaw: number | undefined) => {
+        const prevColor =
+          prevRaw !== undefined ? RiveColor.fromInt(prevRaw) : undefined;
+        const newColorInput =
+          typeof valueOrUpdater === 'function'
+            ? valueOrUpdater(prevColor)
+            : valueOrUpdater;
+        const color =
+          typeof newColorInput === 'string'
+            ? RiveColor.fromHexString(newColorInput)
+            : newColorInput;
+        return color.toInt();
+      });
     },
     [setRawValue]
   );

src/hooks/useRiveProperty.ts

@@ -28,7 +28,12 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     /** Optional override callback for property events (mainly used by triggers) */
     onPropertyEventOverride?: (...args: any[]) => void;
   }
-): [T | undefined, (value: T) => void, Error | null, P | undefined] {
+): [
+  T | undefined,
+  (value: T | ((prevValue: T | undefined) => T)) => void,
+  Error | null,
+  P | undefined,
+] {
   const [value, setValue] = useState<T | undefined>(undefined);
   const [error, setError] = useState<Error | null>(null);
 
@@ -79,14 +84,20 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
 
   // Set the value of the property
   const setPropertyValue = useCallback(
-    (newValue: T) => {
+    (valueOrUpdater: T | ((prevValue: T | undefined) => T)) => {
       if (!property) {
         setError(
           new Error(
             `Cannot set value for property "${path}" because it was not found. Your view model instance may be undefined, or the path may be incorrect.`
           )
         );
       } else {
+        const newValue =
+          typeof valueOrUpdater === 'function'
+            ? (valueOrUpdater as (prevValue: T | undefined) => T)(
+                property.value
+              )
+            : valueOrUpdater;
         property.value = newValue;
       }
     },

src/index.tsx

@@ -52,4 +52,5 @@ export { useRiveList } from './hooks/useRiveList';
 export { useViewModelInstance } from './hooks/useViewModelInstance';
 export { useRiveFile } from './hooks/useRiveFile';
 export { type RiveFileInput } from './hooks/useRiveFile';
+export { type SetValueAction } from './types';
 export { DataBindMode };

src/types.tsx

@@ -1,13 +1,22 @@
+/**
+ * A value or a function that computes a new value from the previous value.
+ * Similar to React's SetStateAction pattern.
+ */
+export type SetValueAction<T> = T | ((prevValue: T | undefined) => T);
+
 export interface UseRivePropertyResult<T> {
   /**
    * The current value of the property.
    */
   value: T | undefined;
   /**
-   * Set the value of the property.
-   * @param value - The value to set the property to.
+   * Set the value of the property. Accepts either a direct value or
+   * a function that receives the previous value and returns the new value.
+   * @example
+   * setValue(10) // Set to 10
+   * setValue((prev) => (prev ?? 0) + 5) // Increment by 5
    */
-  setValue: (value: T) => void;
+  setValue: (value: SetValueAction<T>) => void;
   /**
    * The error if the property is not found.
    */