Extensions: Adds @provideContext and @consumeContext decorators for a better developer experience (#20510)

* feat: adds first draft of a context consume decorator

* feat: uses an options pattern

* feat: changes approach to use `addInitializer` and `queueMicroTask` instead

* feat: adds extra warning if context is consumed on disconnected controllers

* feat: example implementation of consume decorator

* feat: adds support for 'subscribe'

* feat: initial work on provide decorator

* docs: adds license to consume decorator

* feat: adds support for umbraco controllers with `hostConnected`

* feat: uses asPromise to handle one-time subscription instead

* test: adds unit tests for consume decorator

* feat: adds support for controllers through hostConnected injection

* feat: adds support for controllers through hostConnected injection

* test: adds unit tests for provide decorator

* docs: adds more documentation around usage and adds a few warnings in console when it detects wrong usage

* feat: removes unused controllerMap

* docs: adds wording on standard vs legacy decorators

* docs: clarifies usage around internal state

* feat: adds proper return types for decorators

* docs: adds more types

* feat: makes element optional

* feat: makes element optional

* feat: uses @consume in the log viewer to showcase

* chore: cleans up debug info

* feat: renames to `consumeContext` and `provideContext` to stay inline with our own methods

* chore: removes unneeded typings

* chore: removes not needed check

* chore: removes not needed check

* test: adds test for rendered value

* feat: splits up code into several smaller functions

* Apply suggestion from @Copilot

Co-authored-by: Copilot <[email protected]>

* Apply suggestion from @Copilot

Co-authored-by: Copilot <[email protected]>

* Apply suggestion from @Copilot

Co-authored-by: Copilot <[email protected]>

* Apply suggestion from @Copilot

Co-authored-by: Copilot <[email protected]>

* docs: augments code example for creating a context

* Update src/Umbraco.Web.UI.Client/src/packages/log-viewer/workspace/views/search/components/log-viewer-search-input.element.ts

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: iOvergaard

src/Umbraco.Web.UI.Client/src/libs/context-api/consume/context-consume.decorator.test.ts

@@ -0,0 +1,133 @@
+import { UmbContextToken } from '../token/context-token.js';
+import type { UmbContextMinimal } from '../types.js';
+import { UmbContextProvider } from '../provide/context-provider.js';
+import { consumeContext } from './context-consume.decorator.js';
+import { aTimeout, elementUpdated, expect, fixture } from '@open-wc/testing';
+import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
+import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
+import { html, state } from '@umbraco-cms/backoffice/external/lit';
+
+class UmbTestContextConsumerClass implements UmbContextMinimal {
+	public prop: string = 'value from provider';
+	getHostElement() {
+		return undefined as any;
+	}
+}
+
+const testToken = new UmbContextToken<UmbTestContextConsumerClass>('my-test-context');
+
+class MyTestElement extends UmbLitElement {
+	@consumeContext({
+		context: testToken,
+	})
+	@state()
+	contextValue?: UmbTestContextConsumerClass;
+
+	override render() {
+		return html`<div>${this.contextValue?.prop ?? 'no context'}</div>`;
+	}
+}
+
+customElements.define('my-consume-test-element', MyTestElement);
+
+describe('@consume decorator', () => {
+	let provider: UmbContextProvider;
+	let element: MyTestElement;
+
+	beforeEach(async () => {
+		provider = new UmbContextProvider(document.body, testToken, new UmbTestContextConsumerClass());
+		provider.hostConnected();
+
+		element = await fixture<MyTestElement>(`<my-consume-test-element></my-consume-test-element>`);
+	});
+
+	afterEach(() => {
+		provider.destroy();
+		(provider as any) = undefined;
+	});
+
+	it('should receive a context value when provided on the host', () => {
+		expect(element.contextValue).to.equal(provider.providerInstance());
+		expect(element.contextValue?.prop).to.equal('value from provider');
+	});
+
+	it('should render the value from the context', async () => {
+		expect(element).shadowDom.to.equal('<div>value from provider</div>');
+	});
+
+	it('should work when the decorator is used in a controller', async () => {
+		class MyController extends UmbControllerBase {
+			@consumeContext({ context: testToken })
+			contextValue?: UmbTestContextConsumerClass;
+		}
+
+		const controller = new MyController(element);
+
+		await elementUpdated(element);
+
+		expect(element.contextValue).to.equal(provider.providerInstance());
+		expect(controller.contextValue).to.equal(provider.providerInstance());
+	});
+
+	it('should have called the callback first', async () => {
+		let callbackCalled = false;
+
+		class MyCallbackTestElement extends UmbLitElement {
+			@consumeContext({
+				context: testToken,
+				callback: () => {
+					callbackCalled = true;
+				},
+			})
+			contextValue?: UmbTestContextConsumerClass;
+		}
+
+		customElements.define('my-callback-consume-test-element', MyCallbackTestElement);
+
+		const callbackElement = await fixture<MyCallbackTestElement>(
+			`<my-callback-consume-test-element></my-callback-consume-test-element>`,
+		);
+
+		await elementUpdated(callbackElement);
+
+		expect(callbackCalled).to.be.true;
+		expect(callbackElement.contextValue).to.equal(provider.providerInstance());
+	});
+
+	it('should update the context value when the provider instance changes', async () => {
+		const newProviderInstance = new UmbTestContextConsumerClass();
+		newProviderInstance.prop = 'new value from provider';
+
+		const newProvider = new UmbContextProvider(element, testToken, newProviderInstance);
+		newProvider.hostConnected();
+
+		await elementUpdated(element);
+
+		expect(element.contextValue).to.equal(newProvider.providerInstance());
+		expect(element.contextValue?.prop).to.equal(newProviderInstance.prop);
+	});
+
+	it('should be able to consume without subscribing', async () => {
+		class MyNoSubscribeTestController extends UmbControllerBase {
+			@consumeContext({ context: testToken, subscribe: false })
+			contextValue?: UmbTestContextConsumerClass;
+		}
+
+		const controller = new MyNoSubscribeTestController(element);
+		await aTimeout(0); // Wait a tick for promise to resolve
+
+		expect(controller.contextValue).to.equal(provider.providerInstance());
+
+		const newProviderInstance = new UmbTestContextConsumerClass();
+		newProviderInstance.prop = 'new value from provider';
+
+		const newProvider = new UmbContextProvider(element, testToken, newProviderInstance);
+		newProvider.hostConnected();
+
+		await aTimeout(0); // Wait a tick for promise to resolve
+
+		// Should still be the old value
+		expect(controller.contextValue).to.not.equal(newProvider.providerInstance());
+		expect(controller.contextValue?.prop).to.equal('value from provider');
+	});
+});