@blockquote-web-components/blockquote-controller-context-meta 1.4.10 → 1.5.0

package/README.md

@@ -145,35 +145,41 @@ customElements.define('consumer-el', ConsumerEl);
 | `js` | `BaseContextMetaElement`          | BaseContextMetaElement          | ./BaseContextMetaElement.js                 |         |
 | `js` | `contextMetaProvider`             | contextMetaProvider             | ./directives/context-meta-provider.js       |         |
 | `js` | `cacheContextMetaProvider`        | cacheContextMetaProvider        | ./directives/cache-context-meta-provider.js |         |
-| `js` | `contextMetaKeyProvider`          | contextMetaKeyProvider          | ./directives/cache-context-meta-provider.js |         |
 
-### `src/directives/cache-context-meta-provider.js`:
-
-#### Variables
 
-| Name                     | Description | Type |
-| ------------------------ | ----------- | ---- |
-| `contextMetaKeyProvider` |             |      |
+![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
 
-<hr/>
+`contextMetaProviderDirective` is a Lit directive that enables normal DOM elements to act as context providers.
+You can use this directive in both attribute and element bindings in Lit templates.
 
-#### Functions
+> https://github.com/lit/lit/discussions/4690
 
-| Name                       | Description | Parameters                  | Return |
-| -------------------------- | ----------- | --------------------------- | ------ |
-| `cacheContextMetaProvider` |             | `element, contextOrOptions` |        |
+Usage:
+This directive transforms a DOM element into a Lit context provider using the BlockquoteControllerContextMeta class, a
+Lit Reactive Controller that encapsulates controllers provided by [@lit/context](https://lit.dev/docs/data/context/).
 
-<hr/>
+## Features
+- Enables non-Lit elements to provide context.
+- Works seamlessly with [`@lit/context`](https://lit.dev/docs/data/context/).
+- Utilizes `BlockquoteControllerContextMeta`, a Lit Reactive Controller for managing context.
 
-#### Exports
+```js
+  <div ${contextMetaProviderDirective(someValue, myContext)}>
+    <!-- Children can consume the provided context -->
+  </div>
+  //
+  <div data-info="${contextMetaProviderDirective(someValue, myContext)}">
+    <!-- Children can consume the provided context -->
+  </div>
+```
 
-| Kind | Name                       | Declaration              | Module                                        | Package |
-| ---- | -------------------------- | ------------------------ | --------------------------------------------- | ------- |
-| `js` | `contextMetaKeyProvider`   | contextMetaKeyProvider   | src/directives/cache-context-meta-provider.js |         |
-| `js` | `cacheContextMetaProvider` | cacheContextMetaProvider | src/directives/cache-context-meta-provider.js |         |
 
 ### `src/directives/context-meta-provider.js`:
 
+#### class: `README`
+
+<hr/>
+
 #### Variables
 
 | Name                  | Description | Type |
@@ -186,9 +192,24 @@ customElements.define('consumer-el', ConsumerEl);
 
 | Kind | Name                  | Declaration         | Module                                  | Package |
 | ---- | --------------------- | ------------------- | --------------------------------------- | ------- |
+| `js` | `README`              | README              | src/directives/context-meta-provider.js |         |
 | `js` | `contextMetaProvider` | contextMetaProvider | src/directives/context-meta-provider.js |         |
 
----
+### `src/directives/cache-context-meta-provider.js`:
+
+#### Functions
+
+| Name                       | Description                                                                                                                                                                                                                                                                                                                                                                            | Parameters                                                                                                                                | Return |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| `cacheContextMetaProvider` | Return or create a cached BlockquoteControllerContextMeta for (element, context).&#xA;&#xA;This function memoizes BlockquoteControllerContextMeta instances per (element, contextKey).&#xA;If a BlockquoteControllerContextMeta already exists for the given element and context, it is&#xA;returned; otherwise a new BlockquoteControllerContextMeta is created, cached and returned. | `element: HTMLElement\|*, {context = contextMetaSymbol, initialValue}, arg: {  *   context?: *,  *   initialValue?: ContextType<*>,  * }` |        |
+
+<hr/>
+
+#### Exports
+
+| Kind | Name                       | Declaration              | Module                                        | Package |
+| ---- | -------------------------- | ------------------------ | --------------------------------------------- | ------- |
+| `js` | `cacheContextMetaProvider` | cacheContextMetaProvider | src/directives/cache-context-meta-provider.js |         |
 
 ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockquote-web-components/blockquote-controller-context-meta",
-  "version": "1.4.10",
+  "version": "1.5.0",
   "description": "Webcomponent blockquote-controller-context-meta following open-wc recommendations",
   "keywords": [
     "lit",
@@ -122,11 +122,11 @@
   },
   "devDependencies": {
     "@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.12.4",
-    "@blockquote-web-components/blockquote-base-embedded-webview": "^1.13.9"
+    "@blockquote-web-components/blockquote-base-embedded-webview": "^1.13.10"
   },
   "publishConfig": {
     "access": "public"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "3b3617da1d3da881b015dc350d1c9498991b97c7"
+  "gitHead": "e97796a020703685a2f3c51b580cdf3a13198680"
 }

package/src/directives/cache-context-meta-provider.js

@@ -1,15 +1,50 @@
-import {BlockquoteControllerContextMeta} from '../BlockquoteControllerContextMeta.js';
+import {
+  BlockquoteControllerContextMeta,
+  contextMetaSymbol,
+} from '../BlockquoteControllerContextMeta.js';
 
-export const contextMetaKeyProvider = Symbol();
+const metaByElement = new WeakMap();
 
-export const cacheContextMetaProvider = (element, contextOrOptions) => {
-  if (element[contextMetaKeyProvider]) {
-    return element[contextMetaKeyProvider];
+/**
+ * Get or create the per-element Map that holds ContextMeta instances for
+ * different context keys.
+ *
+ * The per-element map is stored in the private WeakMap `metaByElement`.
+ *
+ * @param {HTMLElement|*} element - target used as WeakMap key
+ */
+const getPerElementMap = (element) => {
+  let per = metaByElement.get(element);
+  if (!per) {
+    per = new Map();
+    metaByElement.set(element, per);
   }
+  return per;
+};
+
+/**
+ * Return or create a cached BlockquoteControllerContextMeta for (element, context).
+ *
+ * This function memoizes BlockquoteControllerContextMeta instances per (element, contextKey).
+ * If a BlockquoteControllerContextMeta already exists for the given element and context, it is
+ * returned; otherwise a new BlockquoteControllerContextMeta is created, cached and returned.
+ *
+ * @param {HTMLElement|*} element - element
+ *  @param {{
+ *   context?: *,
+ *   initialValue?: import('@lit/context').ContextType<*>,
+ * }} arg - options for the context provider.
+ */
+export const cacheContextMetaProvider = (element, {context = contextMetaSymbol, initialValue}) => {
+  const options = {context, initialValue};
+  const contextKey = options.context;
+  const perElement = getPerElementMap(element);
+  let meta = perElement.get(contextKey);
 
-  const ctx =
-    contextOrOptions?.context !== undefined ? {...contextOrOptions} : {context: contextOrOptions};
+  if (!meta) {
+    meta = new BlockquoteControllerContextMeta(element, options);
+    perElement.set(contextKey, meta);
+  }
 
-  element[contextMetaKeyProvider] = new BlockquoteControllerContextMeta(element, ctx);
-  return element[contextMetaKeyProvider];
+  return meta;
 };

package/src/directives/context-meta-provider.js

@@ -1,8 +1,10 @@
 import {Directive, directive, PartType} from 'lit/directive.js';
 import {noChange} from 'lit';
-import {cacheContextMetaProvider, contextMetaKeyProvider} from './cache-context-meta-provider.js';
+import {cacheContextMetaProvider} from './cache-context-meta-provider.js';
 
 /**
+ * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
+ *
  * `contextMetaProviderDirective` is a Lit directive that enables normal DOM elements to act as context providers.
  * You can use this directive in both attribute and element bindings in Lit templates.
  *
@@ -17,16 +19,18 @@ import {cacheContextMetaProvider, contextMetaKeyProvider} from './cache-context-
  * - Works seamlessly with [`@lit/context`](https://lit.dev/docs/data/context/).
  * - Utilizes `BlockquoteControllerContextMeta`, a Lit Reactive Controller for managing context.
  *
- * js```
- *   <div ${contextMetaProviderDirective(myContext, someValue)}>
+ * ```js
+ *   <div ${contextMetaProviderDirective(someValue, myContext)}>
  *     <!-- Children can consume the provided context -->
  *   </div>
  *   //
- *   <div data-info="${contextMetaProviderDirective(myContext, someValue)}">
+ *   <div data-info="${contextMetaProviderDirective(someValue, myContext)}">
  *     <!-- Children can consume the provided context -->
  *   </div>
  * ```
  */
+export class README extends Text {}
+
 class ContextMetaProviderDirective extends Directive {
   /** @type {*} */
   #partInfo = undefined;
@@ -50,16 +54,15 @@ class ContextMetaProviderDirective extends Directive {
    * Main render method called by Lit.
    * @param {*} value - The context value to provide.
    * @param {{
-   *  context?: *,
-   *  initialValue?: import('@lit/context').ContextType<*>,
-   * }} context - The context object.
-   * @returns {unknown} - The serialized context value or noChange.
+   *   context?: *,
+   *   initialValue?: import('@lit/context').ContextType<*>,
+   * }} arg - options for the context provider.
    */
-  render(value, context) {
+  render(value, arg) {
     if (value !== this.#currentValue) {
       this.#currentValue = value;
-      this.updateValue(value, context);
-      return this.resolveAttrValue();
+      this.updateValue(value, arg);
+      return this.resolveAttrValue(value);
     }
     return noChange;
   }
@@ -68,25 +71,25 @@ class ContextMetaProviderDirective extends Directive {
    * Updates the context value for the element.
    * @param {*} value - The new context value.
    * @param {{
-   *  context?: *,
-   *  initialValue?: import('@lit/context').ContextType<*>,
-   * }} context - The context object.
+   *   context?: *,
+   *   initialValue?: import('@lit/context').ContextType<*>,
+   * }} options - options for the context provider.
    */
-  updateValue(value, context) {
+  updateValue(value, options) {
     const element = this.#partInfo.element;
-    cacheContextMetaProvider(element, context);
-    element[contextMetaKeyProvider].setValue(value);
+    const metaProvider = cacheContextMetaProvider(element, options);
+    metaProvider.setValue(value);
   }
 
   /**
-   * Decides whether to return the currentValue if the directive is used as an attribute.
-   * @returns {unknown} - The serialized context value or noChange.
+   * Decides whether to return the value if the directive is used as an attribute.
+   * @param {*} value - The context value to provide.
    */
-  resolveAttrValue() {
+  resolveAttrValue(value) {
     if (this.#partInfo.type !== PartType.ATTRIBUTE) {
       return noChange;
     }
-    return this.#currentValue;
+    return value;
   }
 }
 

package/src/index.js

@@ -1,7 +1,4 @@
 export {BlockquoteControllerContextMeta} from './BlockquoteControllerContextMeta.js';
 export {BaseContextMetaElement} from './BaseContextMetaElement.js';
 export {contextMetaProvider} from './directives/context-meta-provider.js';
-export {
-  cacheContextMetaProvider,
-  contextMetaKeyProvider,
-} from './directives/cache-context-meta-provider.js';
+export {cacheContextMetaProvider} from './directives/cache-context-meta-provider.js';