fix!: use undefined for loading state, null for resolved-empty in useViewModelInstance

Author: mfazekas

example/__tests__/hooks.harness.tsx

@@ -34,7 +34,7 @@ function createUseRiveNumberContext(): UseRiveNumberContext {
 }
 
 type UseViewModelInstanceContext = {
-  instance: ViewModelInstance | null;
+  instance: ViewModelInstance | null | undefined;
   age: number | undefined;
 };
 

example/src/exercisers/MenuListExample.tsx

@@ -39,7 +39,16 @@ export default function MenuListExample() {
 }
 
 function MenuList({ file }: { file: RiveFile }) {
-  const { instance } = useViewModelInstance(file, { required: true });
+  const { instance, error } = useViewModelInstance(file);
+
+  if (error) {
+    console.error(error.message);
+    return null;
+  }
+
+  if (!instance) {
+    return <ActivityIndicator size="large" color="#007AFF" />;
+  }
 
   return <MenuListContent file={file} instance={instance} />;
 }

src/hooks/__tests__/useViewModelInstance.test.ts

@@ -362,3 +362,12 @@ describe('useViewModelInstance - ViewModel source', () => {
     expect(result.current.error).toBeNull();
   });
 });
+
+describe('useViewModelInstance - null source', () => {
+  it('should return undefined instance when source is null', () => {
+    const { result } = renderHook(() => useViewModelInstance(null));
+
+    expect(result.current.instance).toBeUndefined();
+    expect(result.current.error).toBeNull();
+  });
+});

src/hooks/useViewModelInstance.ts

@@ -97,7 +97,7 @@ function isRiveFile(source: ViewModelSource | null): source is RiveFile {
 }
 
 type CreateInstanceResult = {
-  instance: ViewModelInstance | null;
+  instance: ViewModelInstance | null | undefined;
   needsDispose: boolean;
   error?: string;
 };
@@ -110,7 +110,7 @@ function createInstance(
   useNew: boolean
 ): CreateInstanceResult {
   if (!source) {
-    return { instance: null, needsDispose: false };
+    return { instance: undefined, needsDispose: false };
   }
 
   if (isRiveViewRef(source)) {
@@ -179,7 +179,8 @@ function createInstance(
 export type UseViewModelInstanceResult =
   | { instance: ViewModelInstance; error: null }
   | { instance: null; error: Error }
-  | { instance: null; error: null };
+  | { instance: null; error: null }
+  | { instance: undefined; error: null };
 
 /**
  * Hook for getting a ViewModelInstance from a RiveFile, ViewModel, or RiveViewRef.
@@ -266,7 +267,9 @@ export type UseViewModelInstanceResult =
 export function useViewModelInstance(
   source: RiveFile,
   params: UseViewModelInstanceFileParams & { required: true }
-): { instance: ViewModelInstance; error: null };
+):
+  | { instance: ViewModelInstance; error: null }
+  | { instance: undefined; error: null };
 export function useViewModelInstance(
   source: RiveFile | null,
   params?: UseViewModelInstanceFileParams
@@ -276,7 +279,9 @@ export function useViewModelInstance(
 export function useViewModelInstance(
   source: ViewModel,
   params: UseViewModelInstanceViewModelParams & { required: true }
-): { instance: ViewModelInstance; error: null };
+):
+  | { instance: ViewModelInstance; error: null }
+  | { instance: undefined; error: null };
 export function useViewModelInstance(
   source: ViewModel | null,
   params?: UseViewModelInstanceViewModelParams
@@ -286,7 +291,9 @@ export function useViewModelInstance(
 export function useViewModelInstance(
   source: RiveViewRef,
   params: UseViewModelInstanceRefParams & { required: true }
-): { instance: ViewModelInstance; error: null };
+):
+  | { instance: ViewModelInstance; error: null }
+  | { instance: undefined; error: null };
 export function useViewModelInstance(
   source: RiveViewRef | null,
   params?: UseViewModelInstanceRefParams
@@ -315,7 +322,7 @@ export function useViewModelInstance(
   const onInit = params?.onInit;
 
   const prevInstanceRef = useRef<{
-    instance: ViewModelInstance | null;
+    instance: ViewModelInstance | null | undefined;
     needsDispose: boolean;
   } | null>(null);
 
@@ -372,5 +379,8 @@ export function useViewModelInstance(
   if (result.instance) {
     return { instance: result.instance, error: null };
   }
+  if (result.instance === undefined) {
+    return { instance: undefined, error: null };
+  }
   return { instance: null, error };
 }