Refactor context handling in NotificationService and DocumentService; add lifecycle methods for host connection management

Author: Luuk Peters

16/umbraco-cms/customizing/foundation/context-api/consume-a-context.md

@@ -301,22 +301,29 @@ export class NotificationService {
             // No callback = one-time use
         );
 
-        // Trigger connection and get result as Promise
-        consumer.hostConnected();
-        const notificationContext = await consumer.asPromise();
-        
-        if (!notificationContext) {
-            throw new Error('Notification context not found!');
-        }
-        
-        notificationContext.peek("positive", {
-            data: {
-                headline: "Success",
-                message: message
+        try {
+            // Trigger connection and get result as Promise
+            consumer.hostConnected();
+
+            // The promise will reject if the context is not found within one animation frame
+            // You can prevent this with: consumer.asPromise({ preventTimeout: true })
+            const notificationContext = await consumer.asPromise();
+            
+            if (!notificationContext) {
+                throw new Error('Notification context not found!');
             }
-        });
-        
-        // Consumer auto-destroys when no callback provided
+            
+            notificationContext.peek("positive", {
+                data: {
+                    headline: "Success",
+                    message: message
+                }
+            });
+        } finally {
+            // Manually clean up to ensure proper disconnection
+            consumer.hostDisconnected();
+            consumer.destroy();
+        }
     }
 }
 ```
@@ -339,24 +346,60 @@ export class DocumentService {
             UMB_DOCUMENT_WORKSPACE_CONTEXT,
             (context) => {
                 if (context) {
+                    // Context is available
                     console.log("I've got the document workspace context: ", context);
                     this.#workspaceContext = context;
                 } else {
+                    // Context not yet available OR has been removed
+                    // This can happen on initial creation or when unprovided                    
                     console.log("The document workspace context is gone, I will make sure my code disassembles properly.");
                     this.#workspaceContext = null;
                 }
             }
         );
-        
-        // Manually trigger the connection
+    }
+
+    // Public method that should be called by the host element's connectedCallback
+    hostConnected() {
         this.#workspaceContextConsumer.hostConnected();
     }
 
+    // Public method that should be called by the host element's disconnectedCallback
+    hostDisconnected() {
+        this.#workspaceContextConsumer.hostDisconnected();
+    }
+
     destroy() {
         // Manually clean up
-        this.#workspaceContextConsumer.hostDisconnected();
         this.#workspaceContextConsumer.destroy();
     }
 }
+```
+
+To use this service, the host element must call the lifecycle methods:
+
+```javascript
+import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
+import { DocumentService } from './document-service.js';
+
+export default class MyElement extends UmbLitElement {
+    #documentService;
 
+    constructor() {
+        super();
+        this.#documentService = new DocumentService(this);
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        // Notify the service that the host is connected
+        this.#documentService.hostConnected();
+    }
+
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        // Notify the service that the host is disconnected
+        this.#documentService.hostDisconnected();
+    }
+}
 ```

16/umbraco-cms/customizing/foundation/context-api/context-api-fundamentals.md

@@ -28,7 +28,7 @@ The Context API exists to solve common problems in complex user interfaces:
 To understand the Context API, it's important to understand the terminology that is used in the rest of the documentation.
 
 ### Context
-An object that encapsulates both data and methods to interact with that data. This object can be provided to descending DOM elements. A context represents a specific capability or state that multiple elements might need to access. Examples include workspace context, content data, user permissions, or specialized services. Contexts encapsulate both data and methods, making them more than just data containers. Unlike repositories, a context is always only available within the scope of a certain element and its descendants.
+An object that encapsulates both data and methods to interact with that data. This object can be provided to descending DOM elements. A context represents a specific capability or state that multiple elements might need to access. Examples include workspace context, content data, user permissions, or specialized services. Contexts encapsulate both data and methods, making them more than data containers. Unlike repositories, a context is always only available within the scope of a certain element and its descendants.
 
 ### Context provider
 An element that creates and makes a context available to its descending elements. The provider is responsible for the context's lifecycle. One element can provide multiple different contexts if needed.

16/umbraco-cms/customizing/foundation/context-api/provide-a-context.md

@@ -4,18 +4,9 @@ description: >-
   incorporate central logic.
 ---
 
------
-New structure:
-
-Page 3: Creating Contexts
-•	How to create contexts
-•	How to define your own custom tokens (building on the token knowledge from core concepts)
------
-
 # Provide a Context
 
 ## Provide a Context API
-
 The recommended approach is to base your Context API on the `UmbContextBase` class, which provides automatic context registration. The following example shows how it's used:
 
 ```typescript