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

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 (3) hide show
  1. package/README.md +47 -32
  2. package/package.json +2 -2
  3. package/src/BaseContextMetaElement.js +38 -21
package/README.md CHANGED
@@ -1,3 +1,31 @@
1
+ ### `src/BaseContextMetaElement.js`:
2
+
3
+ #### class: `BaseContextMetaElement`
4
+
5
+ ##### Methods
6
+
7
+ | Name | Privacy | Description | Parameters | Return | Inherited From |
8
+ | -------------------------- | ------- | ------------------------------------------------------------ | ------------------------------------ | --------------------------------- | -------------- |
9
+ | `initOrGetContextProvider` | | Initializes or returns the existing context meta controller. | `contextOrOptions: string \| Object` | `BlockquoteControllerContextMeta` | |
10
+
11
+ <details><summary>Private API</summary>
12
+
13
+ ##### Fields
14
+
15
+ | Name | Privacy | Type | Default | Description | Inherited From |
16
+ | ---------------------------- | ------- | ---------------------------------------------- | ----------- | --------------------------------------- | -------------- |
17
+ | `#controllerBaseContextMeta` | private | `BlockquoteControllerContextMeta \| undefined` | `undefined` | Stores the context controller instance. | |
18
+
19
+ </details>
20
+
21
+ <hr/>
22
+
23
+ #### Exports
24
+
25
+ | Kind | Name | Declaration | Module | Package |
26
+ | ---- | ------------------------ | ---------------------- | ----------------------------- | ------- |
27
+ | `js` | `BaseContextMetaElement` | BaseContextMetaElement | src/BaseContextMetaElement.js | |
28
+
1
29
  ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
2
30
 
3
31
  `BlockquoteControllerContextMeta` is a Lit Reactive Controller that encapsulates the controllers provided by
@@ -54,10 +82,12 @@
54
82
  <hr>
55
83
 
56
84
  ### `src/BaseContextMetaElement.js`:
57
-
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.
85
+ `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
+ 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)**
59
87
  > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
60
88
 
89
+ <hr>
90
+
61
91
  ### Demo
62
92
 
63
93
  [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
@@ -80,22 +110,26 @@ It incorporates functionality to handle context consumption and presentation as
80
110
  ];
81
111
  ```
82
112
 
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.
113
+ 2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
84
114
  ```js
85
- setConsumerContext(cc = symbolContextMeta) {
86
- if (!this.controllerBaseContextMeta) {
87
- this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
88
- context: cc,
89
- });
115
+ initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
116
+ const ctx =
117
+ contextOrOptions?.context !== undefined
118
+ ? { ...contextOrOptions }
119
+ : { context: contextOrOptions };
120
+
121
+ if (!this.#controllerBaseContextMeta) {
122
+ this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
123
+ }
124
+ return this.#controllerBaseContextMeta;
90
125
  }
91
- }
92
126
  ```
93
127
 
94
128
  3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
95
129
  ```js
96
130
  connectedCallback() {
97
131
  super.connectedCallback?.();
98
- Object.assign(this, this.role ? {} : { role: 'presentation' });
132
+ Object.assign(this, { role: this.role ?? 'presentation' });
99
133
  }
100
134
  ```
101
135
 
@@ -117,12 +151,12 @@ To demonstrate the utility of BaseContextMetaElement, let's create a derived cla
117
151
  };
118
152
  ```
119
153
 
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.
154
+ 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.
121
155
  ```js
122
156
  constructor() {
123
157
  super();
124
158
  this.surface = undefined;
125
- this.setConsumerContext(consumerContext);
159
+ this.flowController = this.initOrGetContextProvider(consumerContext);
126
160
  }
127
161
  ```
128
162
 
@@ -131,12 +165,11 @@ To demonstrate the utility of BaseContextMetaElement, let's create a derived cla
131
165
  willUpdate(props) {
132
166
  super.willUpdate?.(props);
133
167
  if (props.has('surface')) {
134
- this.controllerBaseContextMeta?.setValue(this.surface);
168
+ this.flowController?.setValue(this.surface);
135
169
  }
136
170
  }
137
171
  ```
138
172
 
139
- > __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
140
173
 
141
174
  ### Usage Example:
142
175
  Here's how you might use the FlownElement in your HTML:
@@ -149,21 +182,3 @@ Here's how you might use the FlownElement in your HTML:
149
182
 
150
183
  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.
151
184
 
152
-
153
- ### `src/BaseContextMetaElement.js`:
154
-
155
- #### class: `BaseContextMetaElement`
156
-
157
- ##### Methods
158
-
159
- | Name | Privacy | Description | Parameters | Return | Inherited From |
160
- | -------------------- | ------- | ------------------------------------------------------------------- | ------------ | ------ | -------------- |
161
- | `setConsumerContext` | | Initializes the context consumer controller if not already present. | `cc: string` | | |
162
-
163
- <hr/>
164
-
165
- #### Exports
166
-
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.1.0",
3
+ "version": "1.1.1",
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": "469697a8884101a339360276153f36bd844a50b1"
106
+ "gitHead": "a425e9d97b373a9e13b86d5b71f9a3799205f41e"
107
107
  }
package/src/BaseContextMetaElement.js CHANGED
@@ -4,9 +4,12 @@ import {
4
4
  contextMetaSymbol,
5
5
  } from './BlockquoteControllerContextMeta.js';
6
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.
7
+ * `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
+ * 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)**
8
9
  * > [Is it possible to make normal dom elements context providers?](https://github.com/lit/lit/discussions/4690)
9
10
  *
11
+ * <hr>
12
+ *
10
13
  * ### Demo
11
14
  *
12
15
  * [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/flow-element)
@@ -29,22 +32,26 @@ import {
29
32
  * ];
30
33
  * ```
31
34
  *
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.
35
+ * 2. The initOrGetContextProvider method allows setting up a context consumer on the element. It creates a new BlockquoteControllerContextMeta if one does not already exist.
33
36
  * ```js
34
- * setConsumerContext(cc = symbolContextMeta) {
35
- * if (!this.controllerBaseContextMeta) {
36
- * this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
37
- * context: cc,
38
- * });
37
+ * initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
38
+ * const ctx =
39
+ * contextOrOptions?.context !== undefined
40
+ * ? { ...contextOrOptions }
41
+ * : { context: contextOrOptions };
42
+ *
43
+ * if (!this.#controllerBaseContextMeta) {
44
+ * this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
45
+ * }
46
+ * return this.#controllerBaseContextMeta;
39
47
  * }
40
- * }
41
48
  * ```
42
49
  *
43
50
  * 3. Set a default role of 'presentation' to ensure it behaves semantically like a non-interactive container.
44
51
  * ```js
45
52
  * connectedCallback() {
46
53
  * super.connectedCallback?.();
47
- * Object.assign(this, this.role ? {} : { role: 'presentation' });
54
+ * Object.assign(this, { role: this.role ?? 'presentation' });
48
55
  * }
49
56
  * ```
50
57
  *
@@ -66,12 +73,12 @@ import {
66
73
  * };
67
74
  * ```
68
75
  *
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.
76
+ * 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.
70
77
  * ```js
71
78
  * constructor() {
72
79
  * super();
73
80
  * this.surface = undefined;
74
- * this.setConsumerContext(consumerContext);
81
+ * this.flowController = this.initOrGetContextProvider(consumerContext);
75
82
  * }
76
83
  * ```
77
84
  *
@@ -80,12 +87,11 @@ import {
80
87
  * willUpdate(props) {
81
88
  * super.willUpdate?.(props);
82
89
  * if (props.has('surface')) {
83
- * this.controllerBaseContextMeta?.setValue(this.surface);
90
+ * this.flowController?.setValue(this.surface);
84
91
  * }
85
92
  * }
86
93
  * ```
87
94
  *
88
- * > __Important__: When extending BaseContextMetaElement, it is essential to use this.controllerBaseContextMeta.
89
95
  *
90
96
  * ### Usage Example:
91
97
  * Here's how you might use the FlownElement in your HTML:
@@ -99,6 +105,12 @@ import {
99
105
  * 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
106
  */
101
107
  export class BaseContextMetaElement extends LitElement {
108
+ /**
109
+ * Stores the context controller instance.
110
+ * @type {BlockquoteControllerContextMeta | undefined}
111
+ */
112
+ #controllerBaseContextMeta = undefined;
113
+
102
114
  static styles = [
103
115
  css`
104
116
  :host {
@@ -112,20 +124,25 @@ export class BaseContextMetaElement extends LitElement {
112
124
  ];
113
125
 
114
126
  /**
115
- * Initializes the context consumer controller if not already present.
116
- * @param {string} [cc=contextMetaSymbol] - context name.
127
+ * Initializes or returns the existing context meta controller.
128
+ * @param {string | Object} [contextOrOptions=contextMetaSymbol] - context name.
129
+ * @returns {BlockquoteControllerContextMeta} The instance of the context meta.
117
130
  */
118
- setConsumerContext(cc = contextMetaSymbol) {
119
- if (!this.controllerBaseContextMeta) {
120
- this.controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, {
121
- context: cc,
122
- });
131
+ initOrGetContextProvider(contextOrOptions = contextMetaSymbol) {
132
+ const ctx =
133
+ contextOrOptions?.context !== undefined
134
+ ? { ...contextOrOptions }
135
+ : { context: contextOrOptions };
136
+
137
+ if (!this.#controllerBaseContextMeta) {
138
+ this.#controllerBaseContextMeta = new BlockquoteControllerContextMeta(this, ctx);
123
139
  }
140
+ return this.#controllerBaseContextMeta;
124
141
  }
125
142
 
126
143
  connectedCallback() {
127
144
  super.connectedCallback?.();
128
- Object.assign(this, this.role ? {} : { role: 'presentation' });
145
+ Object.assign(this, { role: this.role ?? 'presentation' });
129
146
  }
130
147
 
131
148
  render() {