docs: better docs for useViewModel hook

Author: js2me

.changeset/puny-turkeys-itch.md

@@ -0,0 +1,5 @@
+---
+"mobx-view-model": patch
+---
+
+better documentation for `useViewModel` React hook

docs/.vitepress/config.mts

@@ -184,6 +184,19 @@ export default defineConfig({
                 link: '/react/api/only-view-model',
               }
             ]
+          },
+          {
+            text: 'Errors',
+            items: [
+              {
+                text: '#1: Active ViewModel not found',
+                link: '/react/errors/1',
+              },
+              {
+                text: '#2: ViewModel not found',
+                link: '/react/errors/2',
+              }
+            ]
           }
         ],
       },

docs/react/errors/1.md

@@ -0,0 +1,50 @@
+# Minified error `#1`: Active `ViewModel` not found   
+
+This happened because [`vmLookup`](/api/other/view-model-lookup) for hook [`useViewModel`](/react/api/use-view-model) is not provided and hook trying to lookup active view model using `ActiveViewModelContext` which works only with using [`withViewModel`](/react/api/with-view-model) HOC.   
+
+
+## Explanation:  
+
+This usage of hook [`useViewModel`](/react/api/use-view-model)   
+
+```tsx
+const model = useViewModel<YourVM>();
+```
+
+Will use `ActiveViewModelContext` which exist only with usage [`withViewModel`](/react/api/with-view-model) HOC.   
+
+Also this can be happened if you are trying to get access to active `ViewModel` which is not exist in current React render tree:   
+
+```tsx
+<Component1>
+  <ComponentAChild1>
+    <Component>
+      useViewModel<YourVM>()
+    </Component>
+  </ComponentAChild1>
+  <YourVMComponent /> - this provide active `ViewModel` (withViewModel)
+</Component1>
+```
+
+## Potential solution
+
+The potential solution to this problem is to pass the [`vmLookup`](/api/other/view-model-lookup) to the hook [`withViewModel`](/react/api/with-view-model)   
+
+```tsx
+const model = useViewModel(YourVM);
+const model = useViewModel('idofyourvm');
+```
+
+Or use `useViewModel<YourVM>()` with correct provided active `ViewModel` React render tree:   
+
+```tsx
+<YourVMComponent> - this provide active `ViewModel` (withViewModel)
+  <Component1>
+    <ComponentAChild1>
+      <Component>
+        useViewModel<YourVM>()
+      </Component>
+    </ComponentAChild1>
+  </Component1>
+</YourVMComponent>
+```

docs/react/errors/2.md

@@ -0,0 +1,25 @@
+# Minified error `#2`: `ViewModel` not found  
+
+This happened because your [`vmLookup`](/api/other/view-model-lookup) provided for hook [`useViewModel`](/react/api/use-view-model) is not found in [`ViewModelStore`](/api/view-model-store/overview).   
+
+
+## Explanation:  
+
+Hook 
+
+```tsx
+const model = useViewModel(YourVM);
+```
+
+Will use [`ViewModelStore`](/api/view-model-store/overview) to find your instance of provided `YourVM` [`ViewModel`](/api/view-models/overview).  
+It means that your `ViewModel` is not created yet and not registered in `ViewModelStore` or you have not declared the creation of this `ViewModel` anywhere.   
+
+## Potential solution
+
+Create and register your `ViewModel` using [`useCreateViewModel`](/react/api/use-create-view-model) hook or [`withViewModel`](/react/api/with-view-model) HOC.
+
+```tsx
+const model = useCreateViewModel(YourVM);
+```
+
+Also you can create and register your `ViewModel` using [ViewModelStore.attach() method](/api/view-model-store/interface#attach-viewmodel), but then you will need to completely reproduce the cycle of creating and destroying the `ViewModel`, which is described in the original code of the hook.

src/hooks/use-view-model.ts

@@ -43,12 +43,14 @@ export const useViewModel = <T extends AnyViewModel | AnyViewModelSimple>(
       if (process.env.NODE_ENV !== 'production') {
         console.error(
           'Active ViewModel not found.\n' +
-            'This happens because "vmLookup" for hook "useViewModel" is not provided and hook trying to lookup active view model using ActiveViewModelContext which works only with using "withViewModel" HOC.\n' +
+            'This happened because "vmLookup" for hook "useViewModel" is not provided and hook trying to lookup active view model using ActiveViewModelContext which works only with using "withViewModel" HOC.\n' +
             'Please provide "vmLookup" (first argument for "useViewModel" hook) or use "withViewModel" HOC.\n' +
-            'See docs: https://js2me.github.io/mobx-view-model/react/api/use-view-model.html',
+            'More info: https://js2me.github.io/mobx-view-model/react/errors/1',
         );
       }
-      throw new Error('Active view model not found');
+      throw new Error(
+        'Minified error #1: https://js2me.github.io/mobx-view-model/react/errors/1',
+      );
     }
 
     if (process.env.NODE_ENV !== 'production') {
@@ -75,15 +77,13 @@ export const useViewModel = <T extends AnyViewModel | AnyViewModelSimple>(
       } else {
         throw new Error(
           `View model not found for ${displayName}.\n` +
-            'This happens because your "vmLookup" provided for hook "useViewModel" is not found in "ViewModelStore".\n' +
-            'See docs: https://js2me.github.io/mobx-view-model/react/api/use-view-model.html',
+            'This happened because your "vmLookup" provided for hook "useViewModel" is not found in "ViewModelStore".\n' +
+            'More info: https://js2me.github.io/mobx-view-model/react/errors/2',
         );
       }
     } else {
       throw new Error(
-        `View model not found for ${displayName}.\n` +
-          'This happens because your "vmLookup" provided for hook "useViewModel" is not found in "ViewModelStore".\n' +
-          'See docs: https://js2me.github.io/mobx-view-model/react/api/use-view-model.html',
+        'Minified error #2: https://js2me.github.io/mobx-view-model/react/errors/2',
       );
     }
   }