documentation

src/Umbraco.Web.UI.Client/storybook/stories/context-api.mdx

@@ -4,15 +4,12 @@ import { Meta } from '@storybook/blocks';
 
 # Context API
 
-This element can be used as the base of any Element.
-Do this if you need to Observe Data, Consume or Provide a Context API or use a Resource.
-The Element implements the Controller Host and provides a few shortcut methods for initializing some Controllers.
-
-The methods are (_note this can be out of date, we need to look into how we can ensure this Doc originates from code._)
+The Context API enables connections between Elements and APIs.
+DOM structure defines the context of which an API is exposed for. APIs are provided via an element and can then be consumed by any decending element wthin.
 
 ### Consume a Context API.
 
-From a Umbraco Element:
+From a Umbraco Element or Umbraco Controller:
 
 ```ts
 this.consumeContext('requestThisContextAlias', (context) => {
@@ -21,10 +18,10 @@ this.consumeContext('requestThisContextAlias', (context) => {
 });
 ```
 
-Or with a Controller using a Controller Host(Umbraco Element):
+Or with a Controller using a 'host' reference to Controller Host(Umbraco Element/Controller):
 
 ```ts
-new UmbContextConsumerController(hostElement, 'requestThisContextAlias', (context) => {
+new UmbContextConsumerController(host, 'requestThisContextAlias', (context) => {
 	// Notice this is a subscription, as context might change or a new one appears.
 	console.log("I've got the context", context);
 });
@@ -32,14 +29,14 @@ new UmbContextConsumerController(hostElement, 'requestThisContextAlias', (contex
 
 ### Provide a Context API.
 
-From a Umbraco Element:
+From a Umbraco Element or Umbraco Controller:
 
 ```ts
 this.provideContext('myContextAlias', new MyContextApi());
 ```
 
-Or with a Controller using a Controller Host(Umbraco Element):
+Or with a Controller using a 'host' reference to Controller Host(Umbraco Element/Controller):
 
 ```ts
-new UmbContextProviderController(hostElement, 'myContextAlias', new MyContextApi());
+new UmbContextProviderController(host, 'myContextAlias', new MyContextApi());
 ```

src/Umbraco.Web.UI.Client/storybook/stories/getting-started.mdx

@@ -15,17 +15,16 @@ There is a few words that covers certain concepts, which is good to learn to eas
 - **Store** A API representing data, generally coming from the server. Most stores would talk with one or more resources. [Go to Store Guide](?path=/docs/guides-store--docs)
 
 - **State** A reactive container holding data, when data is changed all its Observables will be notified.
-- **Observable** An observable is the hook for others to subscribe to the data or part of the data of a State.
+- **Observable** An observable is the hook for others to subscribe to the data of a State.
 - **Observe** Observe is the term of what we do when subscriping to a Observable, We observe and observable.
 
 - **Context-API** The name of the system used to serve APIs(instances/classes) that for a certain context in the DOM. An API that is served via the Context-API is called a Context [Go to Context API Guide](?path=/docs/guides-context-api--docs)
 - **Context Provider** One that provides a class instance as a Context API.
 - **Context Consumer** One that consumer/subscripes to a class instance as a Context API.
 
-- **Controller** An abstract term for a things that hooks into the lifecycle of a element. Many things in our system is Controllers, As a example notice these controllers:
-- **Context Provider Controller** A Context Provider as a Controller, this make its easy to implement a Context Provider.
-- **Context Consumer Controller** A Context Consumer as a Controller, this make its easy to implement a Context Consumer.
-- **Observer Controller** A Controller for handling the observe subscription for a Observable.
+- **Controller** An abstract term for a things that hooks into the lifecycle of a element. Many things in our system is Controllers. [Go to Controller Guide](?path=/docs/guides-controller--docs)
+- **Umbraco Controller** Enables hosting controllers. Additionally it provides few shortcut methods for initializing core Umbraco Controllers.
 
-- **Controller Host** The element that can host one or more controllers.
-- **Umbraco Element** The UmbLitElement or UmbElemenMixin is a implementation of the Controller Host as an element. Using this as your base element provides a few methods that makes life easier. [Go to Umbraco Element Guide](?path=/docs/guides-umbraco-element--docs)
+- **Controller Host** A class which can host controllers.
+- **Controller Host Element** The element that can host controllers.
+- **Umbraco Element** The `UmbLitElement` or `UmbElemenMixin` enables hosting controllers. Additionally it provides few shortcut methods for initializing core Umbraco Controllers. [Go to Umbraco Element Guide](?path=/docs/guides-umbraco-element--docs)

src/Umbraco.Web.UI.Client/storybook/stories/umb-controller.mdx

@@ -0,0 +1,36 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Guides/Umbraco Controller" parameters={{ previewTabs: { canvas: { hidden: true } } }} />
+
+# Umbraco Controller
+
+This class can be used as the base of any class.
+This will enable Controllers to be hosted in this class. Additionally it provides few shortcut methods for initializing core Umbraco Controllers.
+
+```ts
+observe<T>(source: Observable<T>, callback: (_value: T) => void, unique?: string): UmbObserverController<T>
+
+provideContext<R = unknown>(alias: string | UmbContextToken<R>, instance: R): UmbContextProviderController<R>
+
+consumeContext<R = unknown>(alias: string | UmbContextToken<R>, callback: UmbContextCallback<R>): UmbContextConsumerController<R>
+```
+
+Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is of an unknown type:
+
+```ts
+this.consumeContext('requestThisContextAlias', (context) => {
+	// Notice this is a subscription, as context might change or a new one appears.
+	console.log("I've got the context", context);
+});
+```
+
+Or use the a Context Token to get a typed context:
+
+```ts
+import { UMB_NOTIFICATION_CONTEXT_TOKEN } from '@umbraco-cms/backoffice/notification';
+
+this.consumeContext(UMB_NOTIFICATION_CONTEXT_TOKEN, (context) => {
+	// Notice this is a subscription, as context might change or a new one appears, but the value is strongly typed
+	console.log("I've got the context", context);
+});
+```

src/Umbraco.Web.UI.Client/storybook/stories/umb-element.mdx

@@ -4,11 +4,8 @@ import { Meta } from '@storybook/addon-docs';
 
 # Umbraco Element
 
-This element can be used as the base of any Element.
-Do this if you need to Observe Data, Consume or Provide a Context API or use a Resource.
-The Element implements the Controller Host and provides a few shortcut methods for initializing some Controllers.
-
-The methods are (_note this can be out of date, we need to look into how we can ensure this Doc originates from code._)
+This element can be used as the base of any element.
+This will enable Controllers to be hosted at this element. Additionally it provides few shortcut methods for initializing core Umbraco Controllers.
 
 ```ts
 observe<T>(source: Observable<T>, callback: (_value: T) => void, unique?: string): UmbObserverController<T>
@@ -18,7 +15,7 @@ provideContext<R = unknown>(alias: string | UmbContextToken<R>, instance: R): Um
 consumeContext<R = unknown>(alias: string | UmbContextToken<R>, callback: UmbContextCallback<R>): UmbContextConsumerController<R>
 ```
 
-Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is unknown
+Use these for an smooth consumption, like this request for a Context API using a simple string context, where the callback value is of an unknown type:
 
 ```ts
 this.consumeContext('requestThisContextAlias', (context) => {
@@ -27,12 +24,12 @@ this.consumeContext('requestThisContextAlias', (context) => {
 });
 ```
 
-Or use the UmbContextToken type to define the type of the context, like this
+Or use the a Context Token to get a typed context:
 
 ```ts
-const contextAlias = new UmbContextToken<SomeType>('SomeTypeAlias', 'description of context for debugging purposes');
+import { UMB_NOTIFICATION_CONTEXT_TOKEN } from '@umbraco-cms/backoffice/notification';
 
-this.consumeContext(contextAlias, (context) => {
+this.consumeContext(UMB_NOTIFICATION_CONTEXT_TOKEN, (context) => {
 	// Notice this is a subscription, as context might change or a new one appears, but the value is strongly typed
 	console.log("I've got the context", context);
 });