@blockquote-web-components/blockquote-controller-context-meta 1.1.3 → 1.1.4
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.
- package/README.md +131 -133
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,5 +1,136 @@
|
|
|
1
1
|
|
|
2
2
|
|
|
3
|
+
`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.
|
|
4
|
+
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)**
|
|
5
|
+
> [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
|
|
6
|
+
|
|
7
|
+
<hr>
|
|
8
|
+
|
|
9
|
+
### Demo
|
|
10
|
+
|
|
11
|
+
[](https://stackblitz.com/github/oscarmarina/flow-element)
|
|
12
|
+
|
|
13
|
+
### Features
|
|
14
|
+
It incorporates functionality to handle context consumption and presentation as a standard block element.
|
|
15
|
+
|
|
16
|
+
1. The `:host` CSS rules ensure the element behaves like a block-level element and respects the `hidden` attribute to hide itself.
|
|
17
|
+
```js
|
|
18
|
+
static styles = [
|
|
19
|
+
css`
|
|
20
|
+
:host {
|
|
21
|
+
display: block;
|
|
22
|
+
}
|
|
23
|
+
:host([hidden]),
|
|
24
|
+
[hidden] {
|
|
25
|
+
display: none !important;
|
|
26
|
+
}
|
|
27
|
+
`,
|
|
28
|
+
];
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
|
|
32
|
+
```js
|
|
33
|
+
initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
|
|
34
|
+
const ctx =
|
|
35
|
+
contextOrOptions?.context !== undefined
|
|
36
|
+
? { ...contextOrOptions }
|
|
37
|
+
: { context: contextOrOptions };
|
|
38
|
+
|
|
39
|
+
if (!this.#controllerBaseContextMeta) {
|
|
40
|
+
this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
|
|
41
|
+
}
|
|
42
|
+
return this.#controllerBaseContextMeta;
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
|
|
47
|
+
```js
|
|
48
|
+
connectedCallback() {
|
|
49
|
+
super.connectedCallback?.();
|
|
50
|
+
Object.assign(this, { role: this.role ?? 'presentation' });
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
4. The render method includes a <slot>, which allows this element to be a flexible container for any child content, mimicking the behavior of a [flow element](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#flow_content).
|
|
55
|
+
```js
|
|
56
|
+
render() {
|
|
57
|
+
return html`<slot></slot>`;
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
### Usage Example: FlownElement
|
|
63
|
+
To demonstrate the utility of BaseContextMetaElement, let's create a derived class called FlownElement:
|
|
64
|
+
|
|
65
|
+
1. Define Properties: The surface property is declared with reflection, allowing it to influence rendering and context behavior dynamically.
|
|
66
|
+
```js
|
|
67
|
+
static properties = {
|
|
68
|
+
surface: { reflect: true },
|
|
69
|
+
};
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
```js
|
|
74
|
+
constructor() {
|
|
75
|
+
super();
|
|
76
|
+
this.surface = undefined;
|
|
77
|
+
this.flowController = this.initOrGetContextProvider(consumerContext);
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
3. Update Context Values: The willUpdate lifecycle method updates the context value whenever the surface property changes, ensuring context-sensitive operations react appropriately.
|
|
82
|
+
```js
|
|
83
|
+
willUpdate(props) {
|
|
84
|
+
super.willUpdate?.(props);
|
|
85
|
+
if (props.has('surface')) {
|
|
86
|
+
this.flowController?.setValue(this.surface);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
### Usage Example:
|
|
93
|
+
Here's how you might use the FlownElement in your HTML:
|
|
94
|
+
|
|
95
|
+
```html
|
|
96
|
+
<flow-element surface="dim">
|
|
97
|
+
<!-- Child content that can consume context from this provider -->
|
|
98
|
+
</flow-element>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
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.
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
### `src/BaseContextMetaElement.js`:
|
|
105
|
+
|
|
106
|
+
#### class: `BaseContextMetaElement`
|
|
107
|
+
|
|
108
|
+
##### Methods
|
|
109
|
+
|
|
110
|
+
| Name | Privacy | Description | Parameters | Return | Inherited From |
|
|
111
|
+
| -------------------------- | ------- | ------------------------------------------------------------ | ------------------------------------ | --------------------------------- | -------------- |
|
|
112
|
+
| `initOrGetContextProvider` | | Initializes or returns the existing context meta controller. | `contextOrOptions: string \| Object` | `BlockquoteControllerContextMeta` | |
|
|
113
|
+
|
|
114
|
+
<details><summary>Private API</summary>
|
|
115
|
+
|
|
116
|
+
##### Fields
|
|
117
|
+
|
|
118
|
+
| Name | Privacy | Type | Default | Description | Inherited From |
|
|
119
|
+
| ---------------------------- | ------- | ---------------------------------------------- | ----------- | --------------------------------------- | -------------- |
|
|
120
|
+
| `#controllerBaseContextMeta` | private | `BlockquoteControllerContextMeta \| undefined` | `undefined` | Stores the context controller instance. | |
|
|
121
|
+
|
|
122
|
+
</details>
|
|
123
|
+
|
|
124
|
+
<hr/>
|
|
125
|
+
|
|
126
|
+
#### Exports
|
|
127
|
+
|
|
128
|
+
| Kind | Name | Declaration | Module | Package |
|
|
129
|
+
| ---- | ------------------------ | ---------------------- | ----------------------------- | ------- |
|
|
130
|
+
| `js` | `BaseContextMetaElement` | BaseContextMetaElement | src/BaseContextMetaElement.js | |
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
|
|
3
134
|
`BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by [@lit/context](https://lit.dev/docs/data/context/)
|
|
4
135
|
|
|
5
136
|
**Features:**
|
|
@@ -146,136 +277,3 @@ customElements.define('consumer-el', ConsumerEl);
|
|
|
146
277
|
| ---- | --------------------------------- | ------------------------------- | ------------------------------------ | ------- |
|
|
147
278
|
| `js` | `BlockquoteControllerContextMeta` | BlockquoteControllerContextMeta | ./BlockquoteControllerContextMeta.js | |
|
|
148
279
|
| `js` | `BaseContextMetaElement` | BaseContextMetaElement | ./BaseContextMetaElement.js | |
|
|
149
|
-
|
|
150
|
-
<hr>
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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.
|
|
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)**
|
|
156
|
-
> [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
|
|
157
|
-
|
|
158
|
-
<hr>
|
|
159
|
-
|
|
160
|
-
### Demo
|
|
161
|
-
|
|
162
|
-
[](https://stackblitz.com/github/oscarmarina/flow-element)
|
|
163
|
-
|
|
164
|
-
### Features
|
|
165
|
-
It incorporates functionality to handle context consumption and presentation as a standard block element.
|
|
166
|
-
|
|
167
|
-
1. The `:host` CSS rules ensure the element behaves like a block-level element and respects the `hidden` attribute to hide itself.
|
|
168
|
-
```js
|
|
169
|
-
static styles = [
|
|
170
|
-
css`
|
|
171
|
-
:host {
|
|
172
|
-
display: block;
|
|
173
|
-
}
|
|
174
|
-
:host([hidden]),
|
|
175
|
-
[hidden] {
|
|
176
|
-
display: none !important;
|
|
177
|
-
}
|
|
178
|
-
`,
|
|
179
|
-
];
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
|
|
183
|
-
```js
|
|
184
|
-
initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
|
|
185
|
-
const ctx =
|
|
186
|
-
contextOrOptions?.context !== undefined
|
|
187
|
-
? { ...contextOrOptions }
|
|
188
|
-
: { context: contextOrOptions };
|
|
189
|
-
|
|
190
|
-
if (!this.#controllerBaseContextMeta) {
|
|
191
|
-
this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
|
|
192
|
-
}
|
|
193
|
-
return this.#controllerBaseContextMeta;
|
|
194
|
-
}
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
|
|
198
|
-
```js
|
|
199
|
-
connectedCallback() {
|
|
200
|
-
super.connectedCallback?.();
|
|
201
|
-
Object.assign(this, { role: this.role ?? 'presentation' });
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
4. The render method includes a <slot>, which allows this element to be a flexible container for any child content, mimicking the behavior of a [flow element](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#flow_content).
|
|
206
|
-
```js
|
|
207
|
-
render() {
|
|
208
|
-
return html`<slot></slot>`;
|
|
209
|
-
}
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
### Usage Example: FlownElement
|
|
214
|
-
To demonstrate the utility of BaseContextMetaElement, let's create a derived class called FlownElement:
|
|
215
|
-
|
|
216
|
-
1. Define Properties: The surface property is declared with reflection, allowing it to influence rendering and context behavior dynamically.
|
|
217
|
-
```js
|
|
218
|
-
static properties = {
|
|
219
|
-
surface: { reflect: true },
|
|
220
|
-
};
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
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.
|
|
224
|
-
```js
|
|
225
|
-
constructor() {
|
|
226
|
-
super();
|
|
227
|
-
this.surface = undefined;
|
|
228
|
-
this.flowController = this.initOrGetContextProvider(consumerContext);
|
|
229
|
-
}
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
3. Update Context Values: The willUpdate lifecycle method updates the context value whenever the surface property changes, ensuring context-sensitive operations react appropriately.
|
|
233
|
-
```js
|
|
234
|
-
willUpdate(props) {
|
|
235
|
-
super.willUpdate?.(props);
|
|
236
|
-
if (props.has('surface')) {
|
|
237
|
-
this.flowController?.setValue(this.surface);
|
|
238
|
-
}
|
|
239
|
-
}
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
### Usage Example:
|
|
244
|
-
Here's how you might use the FlownElement in your HTML:
|
|
245
|
-
|
|
246
|
-
```html
|
|
247
|
-
<flow-element surface="dim">
|
|
248
|
-
<!-- Child content that can consume context from this provider -->
|
|
249
|
-
</flow-element>
|
|
250
|
-
```
|
|
251
|
-
|
|
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.
|
|
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.
|
|
3
|
+
"version": "1.1.4",
|
|
4
4
|
"description": "Webcomponent blockquote-controller-context-meta following open-wc recommendations",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"lit",
|
|
@@ -93,15 +93,15 @@
|
|
|
93
93
|
},
|
|
94
94
|
"dependencies": {
|
|
95
95
|
"@lit/context": "^1.1.0",
|
|
96
|
-
"lit": "^3.
|
|
96
|
+
"lit": "^3.2.0"
|
|
97
97
|
},
|
|
98
98
|
"devDependencies": {
|
|
99
|
-
"@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.9.
|
|
100
|
-
"@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.
|
|
99
|
+
"@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.9.2",
|
|
100
|
+
"@blockquote-web-components/blockquote-base-embedded-webview": "^1.11.3"
|
|
101
101
|
},
|
|
102
102
|
"publishConfig": {
|
|
103
103
|
"access": "public"
|
|
104
104
|
},
|
|
105
105
|
"customElements": "custom-elements.json",
|
|
106
|
-
"gitHead": "
|
|
106
|
+
"gitHead": "dd2f576611bceb2c8e2b9456b8a22a704b8c6148"
|
|
107
107
|
}
|