@blockquote-web-components/blockquote-controller-context-meta 1.1.0 → 1.1.2

package/README.md

@@ -1,6 +1,102 @@
 ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
 
-`BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by
+`BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by [@lit/context](https://lit.dev/docs/data/context/)
+
+**Features:**
+- It enables a component to serve as both a provider and a consumer.
+- It places the consumer after the first update to reduce the chance of a consumer in LightDOM requesting a context that currently lacks a provider.
+- Create a context object using a global symbol (Symbol.for('my-context')).
+
+<hr>
+
+### Demo
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/blockquote-web-components/tree/main/packages/controllers/blockquote-controller-context-meta)
+
+### Usage
+- [Lit examples context-basics](https://lit.dev/playground/#sample=examples/context-basics)
+```js
+
+import { html, LitElement, css } from 'lit';
+import { BlockquoteControllerContextMeta } from '@blockquote-web-components/blockquote-controller-context-meta';
+
+export class ProviderEl extends LitElement {
+  static styles = css`
+    slot {
+      display: block;
+      border: dashed 4px grey;
+      padding: 0px 10px;
+    }
+
+    :host {
+      display: block;
+      border: solid 4px gainsboro;
+      padding: 2px;
+    }
+
+    h3 {
+      margin-top: 0;
+    }
+  `;
+
+  static properties = {
+    data: {},
+  };
+
+  constructor() {
+    super();
+    this._provider = new BlockquoteControllerContextMeta(this, {
+      context: 'contextKey', // String used as key in Symbol.for when creating context with createContext(Symbol.for(context))
+    });
+
+    this.data = 'Initial';
+  }
+
+   // `data` will be provided to any consumer that is in the DOM tree below it.
+  set data(value) {
+    this._data = value;
+    this._provider.setValue(value);
+  }
+
+  get data() {
+    return this._data;
+  }
+
+  render() {
+    return html`
+      <h3>Provider's data: <code>${this.data}</code></h3>
+      <slot></slot>
+    `;
+  }
+}
+customElements.define('provider-el', ProviderEl);
+
+export class ConsumerEl extends LitElement {
+  _consumer = new BlockquoteControllerContextMeta(this, {
+    context: 'contextKey', // String used as key in Symbol.for when creating context with createContext(Symbol.for(context))
+    callback: (v) => {
+      this.setAttribute('data-callback', v);
+    },
+  });
+
+
+  // `providedData` will be populated by the first ancestor element which
+  // provides a value for `context`.
+
+  get providedData() {
+    return this._consumer.value;
+  }
+
+  render() {
+    return html`<h3>Consumer data: <code>${this.providedData}</code></h3>
+      <hr />
+      <slot></slot>`;
+  }
+}
+customElements.define('consumer-el', ConsumerEl);
+```
+
+ <hr>
 
 
 ### `src/BlockquoteControllerContextMeta.js`:
@@ -53,11 +149,14 @@
 
 <hr>
 
-### `src/BaseContextMetaElement.js`:
+![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
 
-`BaseContextMetaElement` leverages Lit's features and Context API capabilities to facilitate the creation of a component that can be used in place of a standard element, such as a `div`, thus simplifying the use of contexts.
+`BaseContextMetaElement` is inspired by the concept of 'Customized Built-in Elements', focusing on extending native HTML elements like `div` using Lit's features and the Context API.
+ This approach simplifies the integration of context providers into a standard elements, enhancing functionality while preserving the core behavior of standard elements. **[All Structural Roles and Their HTML Equivalents](https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/#allstructuralrolesandtheirhtmlequivalents)**
 > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
 
+ <hr>
+
 ### Demo
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
@@ -80,22 +179,26 @@ It incorporates functionality to handle context consumption and presentation as
    ];
    ```
 
-2. The setConsumerContext method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
+2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
    ```js
-   setConsumerContext(cc = symbolContextMeta) {
-     if (!this.controllerBaseContextMeta) {
-       this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
-         context: cc,
-       });
+     initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
+       const ctx =
+         contextOrOptions?.context !== undefined
+           ? { ...contextOrOptions }
+           : { context: contextOrOptions };
+
+       if (!this.#controllerBaseContextMeta) {
+         this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
+       }
+       return this.#controllerBaseContextMeta;
      }
-   }
    ```
 
 3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
    ```js
    connectedCallback() {
      super.connectedCallback?.();
-     Object.assign(this, this.role ? {} : { role: 'presentation' });
+     Object.assign(this, { role: this.role ?? 'presentation' });
    }
    ```
 
@@ -117,12 +220,12 @@ To demonstrate the utility of BaseContextMetaElement, let's create a derived cla
   };
   ```
 
-2. Set Context on Construction: The constructor calls setConsumerContext with a specific context, enabling the element to participate in the context API from its inception.
+2. Set Context on Construction: The constructor calls initOrGetContextProvider with a specific context, enabling the element to participate in the context API from its inception.
   ```js
   constructor() {
     super();
     this.surface = undefined;
-    this.setConsumerContext(consumerContext);
+    this.flowController = this.initOrGetContextProvider(consumerContext);
   }
   ```
 
@@ -131,12 +234,11 @@ To demonstrate the utility of BaseContextMetaElement, let's create a derived cla
   willUpdate(props) {
     super.willUpdate?.(props);
     if (props.has('surface')) {
-      this.controllerBaseContextMeta?.setValue(this.surface);
+      this.flowController?.setValue(this.surface);
     }
   }
   ```
 
-> __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
 
 ### Usage Example:
 Here's how you might use the FlownElement in your HTML:
@@ -156,9 +258,19 @@ With this setup, FlownElement behaves like a [flow element](https://developer.mo
 
 ##### Methods
 
-| Name                 | Privacy | Description                                                         | Parameters   | Return | Inherited From |
-| -------------------- | ------- | ------------------------------------------------------------------- | ------------ | ------ | -------------- |
-| `setConsumerContext` |         | Initializes the context consumer controller if not already present. | `cc: string` |        |                |
+| Name                       | Privacy | Description                                                  | Parameters                           | Return                            | Inherited From |
+| -------------------------- | ------- | ------------------------------------------------------------ | ------------------------------------ | --------------------------------- | -------------- |
+| `initOrGetContextProvider` |         | Initializes or returns the existing context meta controller. | `contextOrOptions: string \| Object` | `BlockquoteControllerContextMeta` |                |
+
+<details><summary>Private API</summary>
+
+##### Fields
+
+| Name                         | Privacy | Type                                           | Default     | Description                             | Inherited From |
+| ---------------------------- | ------- | ---------------------------------------------- | ----------- | --------------------------------------- | -------------- |
+| `#controllerBaseContextMeta` | private | `BlockquoteControllerContextMeta \| undefined` | `undefined` | Stores the context controller instance. |                |
+
+</details>
 
 <hr/>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockquote-web-components/blockquote-controller-context-meta",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Webcomponent blockquote-controller-context-meta following open-wc recommendations",
   "keywords": [
     "lit",
@@ -97,11 +97,11 @@
   },
   "devDependencies": {
     "@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.9.1",
-    "@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.0"
+    "@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "469697a8884101a339360276153f36bd844a50b1"
+  "gitHead": "6fe48d5f8dc077b549d3c11ab3541a0a1fe84d58"
 }

package/src/BaseContextMetaElement.js

@@ -4,9 +4,14 @@ import {
   contextMetaSymbol,
 } from './BlockquoteControllerContextMeta.js';
 /**
- * `BaseContextMetaElement` leverages Lit's features and Context API capabilities to facilitate the creation of a component that can be used in place of a standard element, such as a `div`, thus simplifying the use of contexts.
+ * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
+ *
+ * `BaseContextMetaElement` is inspired by the concept of 'Customized Built-in Elements', focusing on extending native HTML elements like `div` using Lit's features and the Context API.
+ *  This approach simplifies the integration of context providers into a standard elements, enhancing functionality while preserving the core behavior of standard elements. **[All Structural Roles and Their HTML Equivalents](https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/#allstructuralrolesandtheirhtmlequivalents)**
  * > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
  *
+ *  <hr>
+ *
  * ### Demo
  *
  * [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
@@ -29,22 +34,26 @@ import {
  *    ];
  *    ```
  *
- * 2. The setConsumerContext method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
+ * 2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
  *    ```js
- *    setConsumerContext(cc = symbolContextMeta) {
- *      if (!this.controllerBaseContextMeta) {
- *        this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
- *          context: cc,
- *        });
+ *      initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
+ *        const ctx =
+ *          contextOrOptions?.context !== undefined
+ *            ? { ...contextOrOptions }
+ *            : { context: contextOrOptions };
+ *
+ *        if (!this.#controllerBaseContextMeta) {
+ *          this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
+ *        }
+ *        return this.#controllerBaseContextMeta;
  *      }
- *    }
  *    ```
  *
  * 3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
  *    ```js
  *    connectedCallback() {
  *      super.connectedCallback?.();
- *      Object.assign(this, this.role ? {} : { role: 'presentation' });
+ *      Object.assign(this, { role: this.role ?? 'presentation' });
  *    }
  *    ```
  *
@@ -66,12 +75,12 @@ import {
  *   };
  *   ```
  *
- * 2. Set Context on Construction: The constructor calls setConsumerContext with a specific context, enabling the element to participate in the context API from its inception.
+ * 2. Set Context on Construction: The constructor calls initOrGetContextProvider with a specific context, enabling the element to participate in the context API from its inception.
  *   ```js
  *   constructor() {
  *     super();
  *     this.surface = undefined;
- *     this.setConsumerContext(consumerContext);
+ *     this.flowController = this.initOrGetContextProvider(consumerContext);
  *   }
  *   ```
  *
@@ -80,12 +89,11 @@ import {
  *   willUpdate(props) {
  *     super.willUpdate?.(props);
  *     if (props.has('surface')) {
- *       this.controllerBaseContextMeta?.setValue(this.surface);
+ *       this.flowController?.setValue(this.surface);
  *     }
  *   }
  *   ```
  *
- * > __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
  *
  * ### Usage Example:
  * Here's how you might use the FlownElement in your HTML:
@@ -99,6 +107,12 @@ import {
  * With this setup, FlownElement behaves like a [flow element](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#flow_content) but provides the additional benefit of context management via Lit's context API, allowing you to seamlessly integrate context-sensitive behavior without altering the parent element hierarchy.
  */
 export class BaseContextMetaElement extends LitElement {
+  /**
+   * Stores the context controller instance.
+   * @type {BlockquoteControllerContextMeta | undefined}
+   */
+  #controllerBaseContextMeta = undefined;
+
   static styles = [
     css`
       :host {
@@ -112,20 +126,25 @@ export class BaseContextMetaElement extends LitElement {
   ];
 
   /**
-   * Initializes the context consumer controller if not already present.
-   * @param {string} [cc=contextMetaSymbol] - context name.
+   * Initializes or returns the existing context meta controller.
+   * @param {string | Object} [contextOrOptions=contextMetaSymbol] - context name.
+   * @returns {BlockquoteControllerContextMeta} The instance of the context meta.
    */
-  setConsumerContext(cc = contextMetaSymbol) {
-    if (!this.controllerBaseContextMeta) {
-      this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
-        context: cc,
-      });
+  initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
+    const ctx =
+      contextOrOptions?.context !== undefined
+        ? { ...contextOrOptions }
+        : { context: contextOrOptions };
+
+    if (!this.#controllerBaseContextMeta) {
+      this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
     }
+    return this.#controllerBaseContextMeta;
   }
 
   connectedCallback() {
     super.connectedCallback?.();
-    Object.assign(this, this.role ? {} : { role: 'presentation' });
+    Object.assign(this, { role: this.role ?? 'presentation' });
   }
 
   render() {

package/src/BlockquoteControllerContextMeta.js

@@ -4,7 +4,7 @@ export const contextMetaSymbol = 'context-meta-symbol';
 /**
  * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
  *
- * `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by @lit/context.
+ * `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by [@lit/context](https://lit.dev/docs/data/context/)
  *
  * **Features:**
  * - It enables a component to serve as both a provider and a consumer.