docs: Add docs about Lifecycle and Events (#2978)

* fix: Notify `onInitialized` after outputs are re-built

More aligned with Android

* docs: Add Mermaid

* docs: Add lifecycle docs

* Update CameraSession+Configuration.swift

docs/docs/guides/ERRORS.mdx

@@ -55,9 +55,9 @@ See [the `CameraError.ts` file](https://github.com/mrousavy/react-native-vision-
 
 ### Runtime Errors
 
-The [`CameraRuntimeError`](/docs/api/classes/CameraRuntimeError) represents any kind of error that occured while mounting the Camera view, or an error that occured during the runtime.
+The [`CameraRuntimeError`](/docs/api/classes/CameraRuntimeError) represents any kind of error that occured in the Camera session, either in one of the outputs or the preview itself.
 
-The `<Camera />` UI Component provides an `onError` function that will be invoked every time an unexpected runtime error occured.
+If the Camera session encounters an error, it will call the [`onError`](/docs/api/interfaces/CameraProps#onerror) event:
 
 ```tsx
 function App() {
@@ -73,6 +73,8 @@ function App() {
 
 The [`CameraCaptureError`](/docs/api/classes/CameraCaptureError) represents any kind of error that occured only while taking a photo or recording a video.
 
+If there was an error during capture, it will be thrown as a JS Error (Promise rejection):
+
 ```tsx
 function App() {
   const camera = useRef<Camera>(null)

docs/docs/guides/LIFECYCLE.mdx

@@ -28,6 +28,79 @@ function App() {
 }
 ```
 
+## Events
+
+VisionCamera emits multiple lifecycle events inside a Camera session. In general, initialization happens first, and start/stop events are emitted later on in the timeline:
+
+```mermaid
+gitGraph LR:
+  branch Camera
+  checkout Camera
+  commit id:" "
+
+  checkout Time
+  commit id:"  "
+  commit id:"   "
+
+  checkout Camera
+  commit id:"onInitialized()"
+
+  branch Preview
+  checkout Preview
+  commit id:"    "
+
+  checkout Time
+  commit id:"     "
+  commit id:"      "
+
+  checkout Camera
+  commit id:"onStarted()"
+
+  checkout Preview
+  commit id:"onPreviewStarted()"
+
+  checkout Time
+  commit id:"      "
+  commit id:"       "
+  commit id:"        "
+  commit id:"        "
+  commit id:"         "
+  commit id:"          "
+
+  checkout Preview
+  commit id:"onPreviewStopped()"
+
+  checkout Camera
+  commit id:"onStopped()"
+```
+
+### The `onInitialized` event
+
+Once a Camera session has been initialized, the [`onInitialized`](/docs/api/interfaces/CameraProps#oninitialized) event will be fired.
+All Camera functions (e.g. [`takePhoto()`](taking-photos)) will be available immediately after the `onInitialized` event has been fired.
+
+The event will be fired everytime Camera outputs are re-created, which happens either if the [`device`](/docs/api/interfaces/CameraProps#device) changes or any output (e.g. [`photo`](/docs/api/interfaces/CameraProps#photo)) is toggled on/off.
+
+### The `onStarted`/`onStopped` events
+
+After the Camera session is initialized it might or might not start streaming - depending on whether [`isActive`](/docs/api/interfaces/CameraProps#isactive) is `true` or `false`.
+
+- `isActive={true}`: The session will start streaming. Once it has started streaming the [`onStarted`](/docs/api/interfaces/CameraProps#onstarted) will be called.
+- `isActive={false}`: The session will stop streaming and eventually call the [`onStopped`](/docs/api/interfaces/CameraProps#onstopped) event.
+
+### The `onPreviewStarted`/`onPreviewStopped` events
+
+Similar to the `onStarted`/`onStopped` events, [`onPreviewStarted`](/docs/api/interfaces/CameraProps#onpreviewstarted)/[`onPreviewStopped`](/docs/api/interfaces/CameraProps#onpreviewstopped) will be called when the Camera started or stopped streaming into the Preview View.
+
+This might also happen when flipping Camera devices (e.g. from back -> front), as the Preview View momentarily stops streaming frames when switching devices.
+
+### The `onError` event
+
+If the Camera encounters a runtime error, the [`onError`](/docs/api/interfaces/CameraProps#onerror) event will be fired.
+It contains a [`CameraRuntimeError`](/docs/api/classes/CameraRuntimeError) with a `code` and `message` that describe the error.
+
+See ["Camera Errors"](errors) for more information.
+
 ## Interruptions
 
 VisionCamera gracefully handles Camera interruptions such as incoming calls, phone overheating, a different app opening the Camera, etc., and will automatically resume the Camera once it becomes available again.

docs/docs/guides/PREVIEW.mdx

@@ -29,6 +29,19 @@ Since the Preview is a separate output stream, disabling it will save resources.
 
 [Skia Frame Processors](/docs/guides/skia-frame-processors) will disable the native Preview to use a custom Skia Canvas instead.
 
+### Start/Stop Events
+
+When starting/stopping the Camera session or when switching Camera devices (e.g. from front -> back), the Preview View will momentarily stop receiving frames and appears "frozen".
+To get notified about pauses in the preview view, use the [`onPreviewStarted`](/docs/api/interfaces/CameraProps#onpreviewstarted) and [`onPreviewStopped`](/docs/api/interfaces/CameraProps#onpreviewstopped) events:
+
+```tsx
+<Camera
+  {...props}
+  onPreviewStarted={() => console.log('Preview started!')}
+  onPreviewStopped={() => console.log('Preview stopped!')}
+/>
+```
+
 ### FPS
 
 The Preview view is running at the same frame rate as the Video stream, configured by the [`fps`](/docs/api/interfaces/CameraProps#fps) prop, or 30 FPS by default.

docs/docusaurus.config.js

@@ -10,7 +10,44 @@ module.exports = {
   favicon: '/favicon.ico',
   organizationName: 'mrousavy',
   projectName: 'react-native-vision-camera',
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
   themeConfig: {
+    /**
+     * @type {import('@docusaurus/theme-mermaid').ThemeConfig['mermaid']}
+     */
+    mermaid: {
+      options: {
+        themeVariables: {
+          git0: '#ffffff00',
+          gitBranchLabel0: '#ffffff00',
+          git1: '#ADD8E6',
+          gitBranchLabel1: '#ffffff',
+          git2: '#ACC8E6',
+          gitBranchLabel2: '#ffffff',
+          commitLabelColor: '#000000',
+          commitLabelBackground: '#ffffff',
+          commitLabelFontSize: 24
+        },
+        fontSize: 40,
+        gantt: {
+          sectionFontSize: 40,
+          fontSize: 40,
+          barGap: 15,
+          topPadding: 15,
+          leftPadding: 400,
+          barHeight: 90
+        },
+        gitGraph: {
+          showBranches: true,
+          rotateCommitLabel: false,
+          parallelCommits: false,
+          mainBranchName: 'Time'
+        }
+      },
+    },
     algolia: {
       appId: 'NRK7PZXU6O',
       apiKey: '33d54e627c4587a6d8dbff79d5209e46',

docs/package.json

@@ -12,21 +12,22 @@
     "clear": "docusaurus clear"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.2.1",
-    "@docusaurus/plugin-google-gtag": "^3.2.1",
-    "@docusaurus/plugin-sitemap": "^3.2.1",
-    "@docusaurus/preset-classic": "^3.2.1",
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/plugin-google-gtag": "^3.4.0",
+    "@docusaurus/plugin-sitemap": "^3.4.0",
+    "@docusaurus/preset-classic": "^3.4.0",
+    "@docusaurus/theme-mermaid": "^3.4.0",
     "@mdx-js/react": "^3.0.1",
-    "@vercel/analytics": "^1.2.2",
-    "clsx": "^2.1.0",
+    "@vercel/analytics": "^1.3.1",
+    "clsx": "^2.1.1",
     "prism-react-renderer": "^2.3.1",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.2.1",
-    "@docusaurus/types": "^3.2.1",
-    "@docusaurus/tsconfig": "^3.2.1",
+    "@docusaurus/module-type-aliases": "^3.4.0",
+    "@docusaurus/tsconfig": "^3.4.0",
+    "@docusaurus/types": "^3.4.0",
     "@types/react": "^18.2.29",
     "docusaurus-plugin-typedoc": "^0.22.0",
     "typedoc": "^0.25.13",