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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +117 -20
  2. package/package.json +3 -3
  3. package/src/BaseContextMetaElement.js +2 -0
  4. package/src/BlockquoteControllerContextMeta.js +1 -1
package/README.md CHANGED
@@ -1,34 +1,102 @@
1
- ### `src/BaseContextMetaElement.js`:
1
+ ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
2
2
 
3
- #### class: `BaseContextMetaElement`
3
+ `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by [@lit/context](https://lit.dev/docs/data/context/)
4
4
 
5
- ##### Methods
5
+ **Features:**
6
+ - It enables a component to serve as both a provider and a consumer.
7
+ - 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.
8
+ - Create a context object using a global symbol (Symbol.for('my-context')).
6
9
 
7
- | Name | Privacy | Description | Parameters | Return | Inherited From |
8
- | -------------------------- | ------- | ------------------------------------------------------------ | ------------------------------------ | --------------------------------- | -------------- |
9
- | `initOrGetContextProvider` | | Initializes or returns the existing context meta controller. | `contextOrOptions: string \| Object` | `BlockquoteControllerContextMeta` | |
10
+ <hr>
10
11
 
11
- <details><summary>Private API</summary>
12
+ ### Demo
12
13
 
13
- ##### Fields
14
+ [![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)
14
15
 
15
- | Name | Privacy | Type | Default | Description | Inherited From |
16
- | ---------------------------- | ------- | ---------------------------------------------- | ----------- | --------------------------------------- | -------------- |
17
- | `#controllerBaseContextMeta` | private | `BlockquoteControllerContextMeta \| undefined` | `undefined` | Stores the context controller instance. | |
16
+ ### Usage
17
+ - [Lit examples context-basics](https://lit.dev/playground/#sample=examples/context-basics)
18
+ ```js
18
19
 
19
- </details>
20
+ import { html, LitElement, css } from 'lit';
21
+ import { BlockquoteControllerContextMeta } from '@blockquote-web-components/blockquote-controller-context-meta';
20
22
 
21
- <hr/>
23
+ export class ProviderEl extends LitElement {
24
+ static styles = css`
25
+ slot {
26
+ display: block;
27
+ border: dashed 4px grey;
28
+ padding: 0px 10px;
29
+ }
22
30
 
23
- #### Exports
31
+ :host {
32
+ display: block;
33
+ border: solid 4px gainsboro;
34
+ padding: 2px;
35
+ }
24
36
 
25
- | Kind | Name | Declaration | Module | Package |
26
- | ---- | ------------------------ | ---------------------- | ----------------------------- | ------- |
27
- | `js` | `BaseContextMetaElement` | BaseContextMetaElement | src/BaseContextMetaElement.js | |
37
+ h3 {
38
+ margin-top: 0;
39
+ }
40
+ `;
28
41
 
29
- ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
42
+ static properties = {
43
+ data: {},
44
+ };
30
45
 
31
- `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by
46
+ constructor() {
47
+ super();
48
+ this._provider = new BlockquoteControllerContextMeta(this, {
49
+ context: 'contextKey', // String used as key in Symbol.for when creating context with createContext(Symbol.for(context))
50
+ });
51
+
52
+ this.data = 'Initial';
53
+ }
54
+
55
+ // `data` will be provided to any consumer that is in the DOM tree below it.
56
+ set data(value) {
57
+ this._data = value;
58
+ this._provider.setValue(value);
59
+ }
60
+
61
+ get data() {
62
+ return this._data;
63
+ }
64
+
65
+ render() {
66
+ return html`
67
+ <h3>Provider's data: <code>${this.data}</code></h3>
68
+ <slot></slot>
69
+ `;
70
+ }
71
+ }
72
+ customElements.define('provider-el', ProviderEl);
73
+
74
+ export class ConsumerEl extends LitElement {
75
+ _consumer = new BlockquoteControllerContextMeta(this, {
76
+ context: 'contextKey', // String used as key in Symbol.for when creating context with createContext(Symbol.for(context))
77
+ callback: (v) => {
78
+ this.setAttribute('data-callback', v);
79
+ },
80
+ });
81
+
82
+
83
+ // `providedData` will be populated by the first ancestor element which
84
+ // provides a value for `context`.
85
+
86
+ get providedData() {
87
+ return this._consumer.value;
88
+ }
89
+
90
+ render() {
91
+ return html`<h3>Consumer data: <code>${this.providedData}</code></h3>
92
+ <hr />
93
+ <slot></slot>`;
94
+ }
95
+ }
96
+ customElements.define('consumer-el', ConsumerEl);
97
+ ```
98
+
99
+ <hr>
32
100
 
33
101
 
34
102
  ### `src/BlockquoteControllerContextMeta.js`:
@@ -81,7 +149,8 @@
81
149
 
82
150
  <hr>
83
151
 
84
- ### `src/BaseContextMetaElement.js`:
152
+ ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
153
+
85
154
  `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.
86
155
  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)**
87
156
  > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
@@ -182,3 +251,31 @@ Here's how you might use the FlownElement in your HTML:
182
251
 
183
252
  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.
184
253
 
254
+
255
+ ### `src/BaseContextMetaElement.js`:
256
+
257
+ #### class: `BaseContextMetaElement`
258
+
259
+ ##### Methods
260
+
261
+ | Name | Privacy | Description | Parameters | Return | Inherited From |
262
+ | -------------------------- | ------- | ------------------------------------------------------------ | ------------------------------------ | --------------------------------- | -------------- |
263
+ | `initOrGetContextProvider` | | Initializes or returns the existing context meta controller. | `contextOrOptions: string \| Object` | `BlockquoteControllerContextMeta` | |
264
+
265
+ <details><summary>Private API</summary>
266
+
267
+ ##### Fields
268
+
269
+ | Name | Privacy | Type | Default | Description | Inherited From |
270
+ | ---------------------------- | ------- | ---------------------------------------------- | ----------- | --------------------------------------- | -------------- |
271
+ | `#controllerBaseContextMeta` | private | `BlockquoteControllerContextMeta \| undefined` | `undefined` | Stores the context controller instance. | |
272
+
273
+ </details>
274
+
275
+ <hr/>
276
+
277
+ #### Exports
278
+
279
+ | Kind | Name | Declaration | Module | Package |
280
+ | ---- | ------------------------ | ---------------------- | ----------------------------- | ------- |
281
+ | `js` | `BaseContextMetaElement` | BaseContextMetaElement | src/BaseContextMetaElement.js | |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockquote-web-components/blockquote-controller-context-meta",
3
- "version": "1.1.1",
3
+ "version": "1.1.2",
4
4
  "description": "Webcomponent blockquote-controller-context-meta following open-wc recommendations",
5
5
  "keywords": [
6
6
  "lit",
@@ -97,11 +97,11 @@
97
97
  },
98
98
  "devDependencies": {
99
99
  "@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.9.1",
100
- "@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.0"
100
+ "@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.1"
101
101
  },
102
102
  "publishConfig": {
103
103
  "access": "public"
104
104
  },
105
105
  "customElements": "custom-elements.json",
106
- "gitHead": "a425e9d97b373a9e13b86d5b71f9a3799205f41e"
106
+ "gitHead": "6fe48d5f8dc077b549d3c11ab3541a0a1fe84d58"
107
107
  }
package/src/BaseContextMetaElement.js CHANGED
@@ -4,6 +4,8 @@ import {
4
4
  contextMetaSymbol,
5
5
  } from './BlockquoteControllerContextMeta.js';
6
6
  /**
7
+ * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
8
+ *
7
9
  * `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.
8
10
  * 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)**
9
11
  * > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
package/src/BlockquoteControllerContextMeta.js CHANGED
@@ -4,7 +4,7 @@ export const contextMetaSymbol = 'context-meta-symbol';
4
4
  /**
5
5
  * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
6
6
  *
7
- * `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by @lit/context.
7
+ * `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by [@lit/context](https://lit.dev/docs/data/context/)
8
8
  *
9
9
  * **Features:**
10
10
  * - It enables a component to serve as both a provider and a consumer.