Add Context API Fundamentals section and improve documentation clarity

Author: Luuk Peters

16/umbraco-cms/SUMMARY.md

@@ -200,6 +200,7 @@
   * [Umbraco Element](customizing/foundation/umbraco-element/README.md)
   * [Lit Element](customizing/foundation/lit-element.md)
   * [Context API](customizing/foundation/context-api/README.md)
+    * [Context API Fundamentals](customizing/foundation/context-api/context-api-fundamentals.md)
     * [Consume a Context](customizing/foundation/context-api/consume-a-context.md)
     * [Provide a Context](customizing/foundation/context-api/provide-a-context.md)
   * [Repositories](customizing/foundation/repositories.md)

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

@@ -1,12 +1,35 @@
 ---
-description: The Context API allows Umbraco backoffice extensions to share data and functionality
+description: >-
+  Learn about the Context API for sharing data and functionality between
+  backoffice extensions through the component hierarchy.
 ---
 
 # Context API
-The Context API in Umbraco is a communication system that allows backoffice extensions to share data and functionality through the component hierarchy. The functionality and data is exposed in `contexts`.
 
-Umbraco provides many built-in contexts for common functionality like workspace management, content editing, and user interfaces. You can also create your own custom contexts when you need to share specific data or services between your extensions.
+The Context API is a powerful communication system in Umbraco's backoffice. It enables extensions to share data and functionality through the component hierarchy without tight coupling. Think of it as a way for different parts of your UI to talk to each other and access shared services.
+
+Contexts are used throughout the Umbraco backoffice to provide access to workspace data, notifications, user information, and many other services. When building custom extensions, you'll often need to consume existing contexts or create your own to share functionality between your components.
+
+## Key Concepts
+
+The Context API is built on a few core principles:
+
+* **Provider-Consumer Pattern**: Parent elements provide contexts that descendant elements can consume
+* **Loose Coupling**: Components don't need direct references to each other
+* **Hierarchical**: Contexts flow down through the DOM tree
+* **Type-Safe**: Context Tokens ensure you get the right context
+
+Whether you're building property editors, workspace extensions, dashboards, or any other backoffice UI, the Context API provides a structured way to access and share functionality.
+
+## [Context API Fundamentals](context-api-fundamentals.md)
+
+Learn the core concepts, terminology, and flow mechanisms of the Context API. Understand how contexts are provided and consumed through the element hierarchy, and explore common context types used throughout Umbraco.
+
+## [Consume a Context](consume-a-context.md)
+
+Learn how to consume contexts in your extensions using one-time references or subscriptions. This guide covers consuming contexts in UI elements, services, and non-UI classes, with practical code examples for each scenario.
+
+## [Provide a Context](provide-a-context.md)
+
+Learn how to create and provide your own custom contexts. Make your data and functionality available to descendant elements in the component hierarchy.
 
-First, we'll cover the fundamentals of the Context API, like the concepts.
-Then we'll consume a context.
-And then we'll create our own context using an example.

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

@@ -1,24 +1,17 @@
 ---
 description: >-
-  Consuming a Context via the Context API is the way to start the communication
-  with the rest of the application
+  Learn how to consume contexts in Umbraco elements using one-time references
+  or subscriptions to access data and functionality through the Context API.
 ---
 # Consume a Context
 There are two ways to consume a context: get a __one-time reference__ to the context, or get a __subscription__ for handling context changes. The Context API is a flexible system where contexts can get disconnected or replaced. A subscription allows for the handling of these changes. However, subscriptions use more resources. They are typically consumed in the constructor, a time when the computer is already processing a lot. Which way to go depends on your use case.
 
-If you need a context from the moment your element loads and you hold on to the context by putting it into a variable, you should always use the subscription. Otherwise you risk holding on to a context that could be disconnected or replaced without you knowing. If you're observing properties of a context, you want to know if the context is still available. In this case, a subscription makes the best sense.
+A one-time reference is great for fire-and-forget events. The key here is that the context is not needed on initialization, but is only needed when a specific criteria is met. For instance, events that occur after user interaction or when a specific function is called. In that case, you just need to get a context, do something and forget about the context after that.
 
-A one-time reference is great for fire-and-forget events in your element. Those include events that occur after user interaction. The key here is that the context is not needed when the element is initialized. It's only needed when a specific criteria is met. We just need to get a context to do something. After that, there is no reason to keep the context. 
-
-When you're dealing with a subscription, it's good practice to consume the context in the constructor for the following reasons:
-
-* The constructor runs once when the element is created. This ensures your context subscription is set up before the element connects to the DOM. This guarantees you won't miss any context updates that occur during the element's initialization.
-* Context consumers created in the constructor are automatically connected when the element enters the DOM (`connectedCallback`). They are disconnected when it's removed (`disconnectedCallback`). You don't need to manually manage this lifecycle—Umbraco's controller system handles it for you.
-* By establishing context subscriptions in the constructor, your element's state is consistent from the moment it's created. This prevents race conditions where the element might render or perform actions before its required contexts are available.
-* Creating context consumers in the constructor is more efficient. This is more efficient than creating them in lifecycle methods that can be called multiple times. For example, `connectedCallback` fires every time the element is added to the DOM.
+If you need a context during initialization and you hold on to the context by putting it into a variable, you should always use a subscription. Otherwise you risk holding on to a context that could be disconnected or replaced without you knowing.
 
 ## Consuming contexts in an element
-An [Umbraco Element](../umbraco-element/) is **any web component** that extends `UmbLitElement` or uses `UmbElementMixin` to wrap its base class. Whether you're building with Lit, vanilla JavaScript, or any other web component framework, you can make it an Umbraco Element. This gives it full access to the Context API.
+An [Umbraco Element](../umbraco-element/) is **any web component** that extends `UmbLitElement` or uses the `UmbElementMixin` to wrap its base class. Whether you're building with Lit, vanilla JavaScript, or any other web component framework, you can make it an Umbraco Element. This gives it full access to the Context API.
 
 Umbraco Elements provide two methods for consuming contexts:
 
@@ -132,6 +125,13 @@ customElements.define('example-element', ExampleElement);
 {% endtabs %}
 
 ### Get as a subscription
+When you're dealing with a subscription, it's good practice to consume the context in the constructor for the following reasons:
+
+* The constructor runs once when the element is created. This ensures your context subscription is set up before the element connects to the DOM. This guarantees you won't miss any context updates that occur during the element's initialization.
+* Context consumers created in the constructor are automatically connected when the element enters the DOM (`connectedCallback`). They are disconnected when it's removed (`disconnectedCallback`). You don't need to manually manage this lifecycle—Umbraco's controller system handles it for you.
+* By establishing context subscriptions in the constructor, your element's state is consistent from the moment it's created. This prevents race conditions where the element might render or perform actions before its required contexts are available.
+* Creating context consumers in the constructor is more efficient. This is more efficient than creating them in lifecycle methods that can be called multiple times. For example, `connectedCallback` fires every time the element is added to the DOM.
+
 The first example uses Lit and that is the way Umbraco builds their elements. If you don't want to use Lit, there is also an HTML element example. Both examples don't have any TypeScript specific code. You can use them in either a JavaScript or TypeScript file.
 
 {% tabs %}

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

@@ -1,5 +1,13 @@
+---
+description: >-
+  Learn about the Context API fundamentals, terminology, and how it enables
+  communication between elements in the Umbraco backoffice through hierarchy.
+---
+
 # Context API fundamentals
-This article explains the Context API fundamentals and terminology. Learn how elements share data through hierarchy and the consume flow mechanism.
+The Context API is a powerful communication system in Umbraco's backoffice. It enables elements to share data and functionality without tight coupling. This article covers the core concepts, terminology, and flow mechanisms you need to understand before working with contexts.
+
+Whether you're building custom property editors, workspace extensions, or complex UI components, understanding the Context API is essential. It provides a structured way to access shared state, services, and functionality throughout the element hierarchy.
 
 ## What is the Context API?
 The Umbraco backoffice is a collection of DOM elements, just like any web application. Elements can be anything: a button, a property editor, a section, a menu option, or a tree. These elements have a hierarchy and form the entire DOM tree that makes up the Umbraco application.