docs: improve auth subscription readability (#455)

Signed-off-by: David Dal Busco <david.dalbusco@outlook.com>

Author: peterpeterparker

docs/build/authentication/development.md

@@ -73,23 +73,26 @@ This will clear the sign-in information stored in IndexedDB.
 
 ---
 
-## Subscription
+## Listening to Auth Changes
 
-You can subscribe to the user state using the subscriber function. This function provides a technical user and triggers whenever the user's state changes.
-
-In other words, using this callback allows you to monitor whether the user is signed in or signed out.
+You can monitor when a user signs in or out using `authSubscribe`. It gives you the current user and notifies you whenever their authentication state changes.
 
 ```typescript
 import { authSubscribe } from "@junobuild/core";
 
+// Reactively track if the user is signed in or signed out
 authSubscribe((user: User | null) => {
   console.log("User:", user);
 });
 ```
 
-If you register the subscriber at the top of your application, it will propagate the user's state accordingly (e.g. `null` when a new user opens the app, the new user's entry when they sign in, the existing user when they refresh the browser within the valid duration, and `null` again when they sign out).
+If you register the subscriber at the top of your application, it will automatically reflect the user's state:
+
+- `null` when the app first loads and the user is not signed in
+- A `User` object when they sign in or refresh while authenticated
+- `null` again when they sign out
 
-Subscribing returns a callback that can be executed to unsubscribe:
+To stop listening, you can call the unsubscribe function returned:
 
 ```typescript
 import { authSubscribe } from "@junobuild/core";
@@ -98,7 +101,7 @@ const unsubscribe = authSubscribe((user: User | null) => {
   console.log("User:", user);
 });
 
-// Above subscriber ends now
+// Stop listening
 unsubscribe();
 ```
 

docs/examples/angular.mdx

@@ -116,14 +116,14 @@ import HowToRun from "./components/how-to-run.md";
 
 The following functions from `@junobuild/core` are used in this example:
 
-| Function        | Purpose/Description                 | Where Used (File/Component)                                                                                                                                                   | Juno Docs/Source Reference                                            |
-| --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `initSatellite` | Initialize Juno Satellite container | [`src/app/app.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/app.component.ts)                                           | [Initialization](../setup-the-sdk#initialization)                     |
-| `authSubscribe` | Subscribe to auth state changes     | [`src/app/services/auth.service.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/services/auth.service.ts)                           | [Subscription](../build/authentication/development#subscription)      |
-| `signIn`        | Sign in user                        | [`src/app/components/login/login.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/login/login.component.ts)     | [Sign-in](../build/authentication/development#sign-in)                |
-| `signOut`       | Sign out user                       | [`src/app/components/logout/logout.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/logout/logout.component.ts) | [Sign-out](../build/authentication/development#sign-out)              |
-| `listDocs`      | List documents in a collection      | [`src/app/services/docs.service.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/services/docs.service.ts)                           | [List documents](../build/datastore/development#list-documents)       |
-| `setDoc`        | Create or update a document         | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts)     | [Add a document](../build/datastore/development#add-a-document)       |
-| `deleteDoc`     | Delete a document                   | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete a document](../build/datastore/development#delete-a-document) |
-| `uploadFile`    | Upload a file to storage            | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts)     | [Upload asset](../build/storage/development#upload-asset)             |
-| `deleteAsset`   | Delete a file from storage          | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete asset](../build/storage/development#delete-asset)             |
+| Function        | Purpose/Description                 | Where Used (File/Component)                                                                                                                                                   | Juno Docs/Source Reference                                                                 |
+| --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `initSatellite` | Initialize Juno Satellite container | [`src/app/app.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/app.component.ts)                                           | [Initialization](../setup-the-sdk#initialization)                                          |
+| `authSubscribe` | Subscribe to auth state changes     | [`src/app/services/auth.service.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/services/auth.service.ts)                           | [Listening to Auth Changes](../build/authentication/development#listening-to-auth-changes) |
+| `signIn`        | Sign in user                        | [`src/app/components/login/login.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/login/login.component.ts)     | [Sign-in](../build/authentication/development#sign-in)                                     |
+| `signOut`       | Sign out user                       | [`src/app/components/logout/logout.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/logout/logout.component.ts) | [Sign-out](../build/authentication/development#sign-out)                                   |
+| `listDocs`      | List documents in a collection      | [`src/app/services/docs.service.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/services/docs.service.ts)                           | [List documents](../build/datastore/development#list-documents)                            |
+| `setDoc`        | Create or update a document         | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts)     | [Add a document](../build/datastore/development#add-a-document)                            |
+| `deleteDoc`     | Delete a document                   | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete a document](../build/datastore/development#delete-a-document)                      |
+| `uploadFile`    | Upload a file to storage            | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts)     | [Upload asset](../build/storage/development#upload-asset)                                  |
+| `deleteAsset`   | Delete a file from storage          | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete asset](../build/storage/development#delete-asset)                                  |

docs/examples/nextjs.mdx

@@ -116,14 +116,14 @@ juno deploy
 
 The following functions from `@junobuild/core` are used in this example:
 
-| Function        | Purpose/Description                 | Where Used (File/Component)                                                                                                          | Juno Docs/Source Reference                                            |
-| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
-| `initSatellite` | Initialize Juno Satellite container | [`src/app/page.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/app/page.tsx)                   | [Initialization](../setup-the-sdk#initialization)                     |
-| `authSubscribe` | Subscribe to auth state changes     | [`src/components/auth.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/auth.tsx)     | [Subscription](../build/authentication/development#subscription)      |
-| `signIn`        | Sign in user                        | [`src/components/login.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/login.tsx)   | [Sign-in](../build/authentication/development#sign-in)                |
-| `signOut`       | Sign out user                       | [`src/components/logout.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/logout.tsx) | [Sign-out](../build/authentication/development#sign-out)              |
-| `listDocs`      | List documents in a collection      | [`src/components/table.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/table.tsx)   | [List documents](../build/datastore/development#list-documents)       |
-| `setDoc`        | Create or update a document         | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx)   | [Add a document](../build/datastore/development#add-a-document)       |
-| `deleteDoc`     | Delete a document                   | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete a document](../build/datastore/development#delete-a-document) |
-| `uploadFile`    | Upload a file to storage            | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx)   | [Upload asset](../build/storage/development#upload-asset)             |
-| `deleteAsset`   | Delete a file from storage          | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete asset](../build/storage/development#delete-asset)             |
+| Function        | Purpose/Description                 | Where Used (File/Component)                                                                                                          | Juno Docs/Source Reference                                                                 |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `initSatellite` | Initialize Juno Satellite container | [`src/app/page.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/app/page.tsx)                   | [Initialization](../setup-the-sdk#initialization)                                          |
+| `authSubscribe` | Subscribe to auth state changes     | [`src/components/auth.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/auth.tsx)     | [Listening to Auth Changes](../build/authentication/development#listening-to-auth-changes) |
+| `signIn`        | Sign in user                        | [`src/components/login.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/login.tsx)   | [Sign-in](../build/authentication/development#sign-in)                                     |
+| `signOut`       | Sign out user                       | [`src/components/logout.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/logout.tsx) | [Sign-out](../build/authentication/development#sign-out)                                   |
+| `listDocs`      | List documents in a collection      | [`src/components/table.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/table.tsx)   | [List documents](../build/datastore/development#list-documents)                            |
+| `setDoc`        | Create or update a document         | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx)   | [Add a document](../build/datastore/development#add-a-document)                            |
+| `deleteDoc`     | Delete a document                   | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete a document](../build/datastore/development#delete-a-document)                      |
+| `uploadFile`    | Upload a file to storage            | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx)   | [Upload asset](../build/storage/development#upload-asset)                                  |
+| `deleteAsset`   | Delete a file from storage          | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete asset](../build/storage/development#delete-asset)                                  |