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

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 CHANGED
@@ -1,138 +1,169 @@
1
1
  ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
2
2
 
3
- `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by @lit/context.
3
+ `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by
4
4
 
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')).
9
5
 
10
- <hr>
6
+ ### `src/BlockquoteControllerContextMeta.js`:
11
7
 
12
- ### Demo
8
+ #### class: `ContextMeta`
13
9
 
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)
10
+ ##### Fields
15
11
 
16
- ### Usage
17
- - [Lit examples context-basics](https://lit.dev/playground/#sample=examples/context-basics)
18
- ```js
12
+ | Name | Privacy | Type | Default | Description | Inherited From |
13
+ | ---------------------- | ------- | ---- | --------------------------------------------------------------------------------------------- | ----------- | -------------- |
14
+ | `value` | | | | | |
15
+ | `context` | | | | | |
16
+ | `initialValue` | | | `initialValue` | | |
17
+ | `callback` | | | `callback` | | |
18
+ | `host` | | | `host` | | |
19
+ | `_contextMetaProvider` | | | `new ContextProvider(this.host, { context: this.context, initialValue: this.initialValue, })` | | |
19
20
 
20
- import { html, LitElement, css } from 'lit';
21
- import { BlockquoteControllerContextMeta } from '@blockquote-web-components/blockquote-controller-context-meta';
21
+ ##### Methods
22
22
 
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
- }
23
+ | Name | Privacy | Description | Parameters | Return | Inherited From |
24
+ | --------------- | ------- | ----------- | ---------- | ------ | -------------- |
25
+ | `setValue` | | | `v, force` | | |
26
+ | `hostConnected` | | | | | |
30
27
 
31
- :host {
32
- display: block;
33
- border: solid 4px gainsboro;
34
- padding: 2px;
35
- }
28
+ <hr/>
36
29
 
37
- h3 {
38
- margin-top: 0;
39
- }
40
- `;
30
+ #### Variables
41
31
 
42
- static properties = {
43
- data: {},
44
- };
32
+ | Name | Description | Type |
33
+ | ------------------- | ----------- | -------- |
34
+ | `contextMetaSymbol` | | `string` |
45
35
 
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
- });
36
+ <hr/>
51
37
 
52
- this.data = 'Initial';
53
- }
38
+ #### Exports
54
39
 
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
- }
40
+ | Kind | Name | Declaration | Module | Package |
41
+ | ---- | --------------------------------- | ----------------- | -------------------------------------- | ------- |
42
+ | `js` | `contextMetaSymbol` | contextMetaSymbol | src/BlockquoteControllerContextMeta.js | |
43
+ | `js` | `BlockquoteControllerContextMeta` | ContextMeta | src/BlockquoteControllerContextMeta.js | |
60
44
 
61
- get data() {
62
- return this._data;
63
- }
45
+ ### `src/index.js`:
64
46
 
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);
47
+ #### Exports
48
+
49
+ | Kind | Name | Declaration | Module | Package |
50
+ | ---- | --------------------------------- | ------------------------------- | ------------------------------------ | ------- |
51
+ | `js` | `BlockquoteControllerContextMeta` | BlockquoteControllerContextMeta | ./BlockquoteControllerContextMeta.js | |
52
+ | `js` | `BaseContextMetaElement` | BaseContextMetaElement | ./BaseContextMetaElement.js | |
73
53
 
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
- });
54
+ <hr>
81
55
 
56
+ ### `src/BaseContextMetaElement.js`:
82
57
 
83
- // `providedData` will be populated by the first ancestor element which
84
- // provides a value for `context`.
58
+ `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.
59
+ > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
85
60
 
86
- get providedData() {
87
- return this._consumer.value;
88
- }
61
+ ### Demo
89
62
 
90
- render() {
91
- return html`<h3>Consumer data: <code>${this.providedData}</code></h3>
92
- <hr />
93
- <slot></slot>`;
63
+ [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
64
+
65
+ ### Features
66
+ It incorporates functionality to handle context consumption and presentation as a standard block element.
67
+
68
+ 1. The `:host` CSS rules ensure the element behaves like a block-level element and respects the `hidden` attribute to hide itself.
69
+ ```js
70
+ static styles = [
71
+ css`
72
+ :host {
73
+ display: block;
74
+ }
75
+ :host([hidden]),
76
+ [hidden] {
77
+ display: none !important;
78
+ }
79
+ `,
80
+ ];
81
+ ```
82
+
83
+ 2. The setConsumerContext method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
84
+ ```js
85
+ setConsumerContext(cc = symbolContextMeta) {
86
+ if (!this.controllerBaseContextMeta) {
87
+ this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
88
+ context: cc,
89
+ });
90
+ }
91
+ }
92
+ ```
93
+
94
+ 3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
95
+ ```js
96
+ connectedCallback() {
97
+ super.connectedCallback?.();
98
+ Object.assign(this, this.role ? {} : { role: 'presentation' });
99
+ }
100
+ ```
101
+
102
+ 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).
103
+ ```js
104
+ render() {
105
+ return html`<slot></slot>`;
106
+ }
107
+ ```
108
+
109
+
110
+ ### Usage Example: FlownElement
111
+ To demonstrate the utility of BaseContextMetaElement, let's create a derived class called FlownElement:
112
+
113
+ 1. Define Properties: The surface property is declared with reflection, allowing it to influence rendering and context behavior dynamically.
114
+ ```js
115
+ static properties = {
116
+ surface: { reflect: true },
117
+ };
118
+ ```
119
+
120
+ 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.
121
+ ```js
122
+ constructor() {
123
+ super();
124
+ this.surface = undefined;
125
+ this.setConsumerContext(consumerContext);
94
126
  }
95
- }
96
- customElements.define('consumer-el', ConsumerEl);
97
- ```
127
+ ```
128
+
129
+ 3. Update Context Values: The willUpdate lifecycle method updates the context value whenever the surface property changes, ensuring context-sensitive operations react appropriately.
130
+ ```js
131
+ willUpdate(props) {
132
+ super.willUpdate?.(props);
133
+ if (props.has('surface')) {
134
+ this.controllerBaseContextMeta?.setValue(this.surface);
135
+ }
136
+ }
137
+ ```
98
138
 
99
- <hr>
139
+ > __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
100
140
 
141
+ ### Usage Example:
142
+ Here's how you might use the FlownElement in your HTML:
101
143
 
102
- ### `src/BlockquoteControllerContextMeta.js`:
144
+ ```html
145
+ <flow-element surface="dim">
146
+ <!-- Child content that can consume context from this provider -->
147
+ </flow-element>
148
+ ```
103
149
 
104
- #### class: `ContextMeta`
150
+ 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.
105
151
 
106
- ##### Fields
107
152
 
108
- | Name | Privacy | Type | Default | Description | Inherited From |
109
- | ---------------------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------- | ----------- | -------------- |
110
- | `value` | | | | | |
111
- | `context` | | | | | |
112
- | `initialValue` | | | `initialValue` | | |
113
- | `callback` | | | `callback` | | |
114
- | `host` | | | `host` | | |
115
- | `_contextMetaProvider` | | | `new ContextProvider(this.host, { context: this.context, initialValue: this.initialValue, })` | | |
153
+ ### `src/BaseContextMetaElement.js`:
154
+
155
+ #### class: `BaseContextMetaElement`
116
156
 
117
157
  ##### Methods
118
158
 
119
- | Name | Privacy | Description | Parameters | Return | Inherited From |
120
- | --------------- | ------- | ----------- | ---------- | ------ | -------------- |
121
- | `setValue` | | | `v, force` | | |
122
- | `hostConnected` | | | | | |
159
+ | Name | Privacy | Description | Parameters | Return | Inherited From |
160
+ | -------------------- | ------- | ------------------------------------------------------------------- | ------------ | ------ | -------------- |
161
+ | `setConsumerContext` | | Initializes the context consumer controller if not already present. | `cc: string` | | |
123
162
 
124
163
  <hr/>
125
164
 
126
165
  #### Exports
127
166
 
128
- | Kind | Name | Declaration | Module | Package |
129
- | ---- | --------------------------------- | ----------- | -------------------------------------- | ------- |
130
- | `js` | `BlockquoteControllerContextMeta` | ContextMeta | src/BlockquoteControllerContextMeta.js | |
131
-
132
- ### `src/index.js`:
133
-
134
- #### Exports
135
-
136
- | Kind | Name | Declaration | Module | Package |
137
- | ---- | --------------------------------- | ------------------------------- | ------------------------------------ | ------- |
138
- | `js` | `BlockquoteControllerContextMeta` | BlockquoteControllerContextMeta | ./BlockquoteControllerContextMeta.js | |
167
+ | Kind | Name | Declaration | Module | Package |
168
+ | ---- | ------------------------ | ---------------------- | ----------------------------- | ------- |
169
+ | `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.0.4",
3
+ "version": "1.1.0",
4
4
  "description": "Webcomponent blockquote-controller-context-meta following open-wc recommendations",
5
5
  "keywords": [
6
6
  "lit",
@@ -103,5 +103,5 @@
103
103
  "access": "public"
104
104
  },
105
105
  "customElements": "custom-elements.json",
106
- "gitHead": "015e61740035c23471a5164f460ce03b05adab32"
106
+ "gitHead": "469697a8884101a339360276153f36bd844a50b1"
107
107
  }
@@ -0,0 +1,136 @@
1
+ import { LitElement, html, css } from 'lit';
2
+ import {
3
+ BlockquoteControllerContextMeta,
4
+ contextMetaSymbol,
5
+ } from './BlockquoteControllerContextMeta.js';
6
+ /**
7
+ * `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.
8
+ * > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
9
+ *
10
+ * ### Demo
11
+ *
12
+ * [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
13
+ *
14
+ * ### Features
15
+ * It incorporates functionality to handle context consumption and presentation as a standard block element.
16
+ *
17
+ * 1. The `:host` CSS rules ensure the element behaves like a block-level element and respects the `hidden` attribute to hide itself.
18
+ * ```js
19
+ * static styles = [
20
+ * css`
21
+ * :host {
22
+ * display: block;
23
+ * }
24
+ * :host([hidden]),
25
+ * [hidden] {
26
+ * display: none !important;
27
+ * }
28
+ * `,
29
+ * ];
30
+ * ```
31
+ *
32
+ * 2. The setConsumerContext method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
33
+ * ```js
34
+ * setConsumerContext(cc = symbolContextMeta) {
35
+ * if (!this.controllerBaseContextMeta) {
36
+ * this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
37
+ * context: cc,
38
+ * });
39
+ * }
40
+ * }
41
+ * ```
42
+ *
43
+ * 3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
44
+ * ```js
45
+ * connectedCallback() {
46
+ * super.connectedCallback?.();
47
+ * Object.assign(this, this.role ? {} : { role: 'presentation' });
48
+ * }
49
+ * ```
50
+ *
51
+ * 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).
52
+ * ```js
53
+ * render() {
54
+ * return html`<slot></slot>`;
55
+ * }
56
+ * ```
57
+ *
58
+ *
59
+ * ### Usage Example: FlownElement
60
+ * To demonstrate the utility of BaseContextMetaElement, let's create a derived class called FlownElement:
61
+ *
62
+ * 1. Define Properties: The surface property is declared with reflection, allowing it to influence rendering and context behavior dynamically.
63
+ * ```js
64
+ * static properties = {
65
+ * surface: { reflect: true },
66
+ * };
67
+ * ```
68
+ *
69
+ * 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.
70
+ * ```js
71
+ * constructor() {
72
+ * super();
73
+ * this.surface = undefined;
74
+ * this.setConsumerContext(consumerContext);
75
+ * }
76
+ * ```
77
+ *
78
+ * 3. Update Context Values: The willUpdate lifecycle method updates the context value whenever the surface property changes, ensuring context-sensitive operations react appropriately.
79
+ * ```js
80
+ * willUpdate(props) {
81
+ * super.willUpdate?.(props);
82
+ * if (props.has('surface')) {
83
+ * this.controllerBaseContextMeta?.setValue(this.surface);
84
+ * }
85
+ * }
86
+ * ```
87
+ *
88
+ * > __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
89
+ *
90
+ * ### Usage Example:
91
+ * Here's how you might use the FlownElement in your HTML:
92
+ *
93
+ * ```html
94
+ * <flow-element surface="dim">
95
+ * <!-- Child content that can consume context from this provider -->
96
+ * </flow-element>
97
+ * ```
98
+ *
99
+ * 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.
100
+ */
101
+ export class BaseContextMetaElement extends LitElement {
102
+ static styles = [
103
+ css`
104
+ :host {
105
+ display: block;
106
+ }
107
+ :host([hidden]),
108
+ [hidden] {
109
+ display: none !important;
110
+ }
111
+ `,
112
+ ];
113
+
114
+ /**
115
+ * Initializes the context consumer controller if not already present.
116
+ * @param {string} [cc=contextMetaSymbol] - context name.
117
+ */
118
+ setConsumerContext(cc = contextMetaSymbol) {
119
+ if (!this.controllerBaseContextMeta) {
120
+ this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
121
+ context: cc,
122
+ });
123
+ }
124
+ }
125
+
126
+ connectedCallback() {
127
+ super.connectedCallback?.();
128
+ Object.assign(this, this.role ? {} : { role: 'presentation' });
129
+ }
130
+
131
+ render() {
132
+ return html`
133
+ <slot></slot>
134
+ `;
135
+ }
136
+ }
@@ -1,5 +1,6 @@
1
1
  import { ReactiveController, ReactiveControllerHost } from 'lit';
2
2
  import { Context, ContextType } from '@lit/context';
3
+ export declare const contextMetaSymbol = 'context-meta-symbol';
3
4
 
4
5
  declare class ContextMeta<
5
6
  TMeta extends Context<unknown, unknown>,
@@ -7,7 +8,7 @@ declare class ContextMeta<
7
8
  > implements ReactiveController
8
9
  {
9
10
  private host;
10
- private context;
11
+ private context?;
11
12
  private initialValue?;
12
13
  private callback?;
13
14
  private _contextMetaProvider;
@@ -19,7 +20,7 @@ declare class ContextMeta<
19
20
  initialValue,
20
21
  callback,
21
22
  }: {
22
- context: string;
23
+ context?: string;
23
24
  initialValue?: ContextType<TMeta>;
24
25
  callback?: (v: ContextType<TMeta>, dispose?: () => void) => void;
25
26
  },
@@ -1,5 +1,6 @@
1
1
  import { createContext, ContextProvider, ContextConsumer } from '@lit/context';
2
2
 
3
+ export const contextMetaSymbol = 'context-meta-symbol';
3
4
  /**
4
5
  * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
5
6
  *
@@ -105,12 +106,12 @@ class ContextMeta {
105
106
  /**
106
107
  * @param {import('lit').ReactiveElement} host - The host object.
107
108
  * @param {{
108
- * context: string,
109
+ * context?: string,
109
110
  * initialValue?: import('@lit/context').ContextType<*>,
110
111
  * callback?: (value: import('@lit/context').ContextType<*>, dispose?: () => void) => void
111
112
  * }} arg - The arguments for the constructor.
112
113
  */
113
- constructor(host, { context, initialValue, callback }) {
114
+ constructor(host, { context = contextMetaSymbol, initialValue, callback }) {
114
115
  this.context = createContext(Symbol.for(context));
115
116
  this.initialValue = initialValue;
116
117
  this.callback = callback;
package/src/index.js CHANGED
@@ -1 +1,2 @@
1
1
  export { BlockquoteControllerContextMeta } from './BlockquoteControllerContextMeta.js';
2
+ export { BaseContextMetaElement } from './BaseContextMetaElement.js';