@twobirds/microcomponents 0.2.0 → 0.2.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 (38) hide show
  1. package/README.md +27 -38
  2. package/dist/MC.min.js +1 -1
  3. package/dist/autoload.min.js +1 -1
  4. package/dist/core/MC.d.ts +5 -2
  5. package/dist/core/MC.d.ts.map +1 -1
  6. package/dist/core/MC.js +52 -4
  7. package/dist/core/elements.d.ts +186 -100
  8. package/dist/core/elements.d.ts.map +1 -1
  9. package/dist/core/elements.js +186 -17
  10. package/dist/core/mcGuards.d.ts +1 -0
  11. package/dist/core/mcGuards.d.ts.map +1 -1
  12. package/dist/core/mcGuards.js +0 -10
  13. package/dist/elements.min.js +1 -1
  14. package/dist/events.min.js +1 -1
  15. package/dist/formValues.min.js +1 -1
  16. package/dist/microcomponents.d.ts +2 -2
  17. package/dist/microcomponents.d.ts.map +1 -1
  18. package/dist/microcomponents.js +2 -2
  19. package/dist/microcomponents.min.js +1 -1
  20. package/dist/observables.min.js +1 -1
  21. package/dist/state/formValues.d.ts +111 -66
  22. package/dist/state/formValues.d.ts.map +1 -1
  23. package/dist/state/formValues.js +132 -68
  24. package/dist/state/observables.d.ts +68 -83
  25. package/dist/state/observables.d.ts.map +1 -1
  26. package/dist/state/observables.js +124 -84
  27. package/dist/utils/autoload.d.ts.map +1 -0
  28. package/dist/{core → utils}/autoload.js +2 -2
  29. package/dist/{core → utils}/events.d.ts +22 -0
  30. package/dist/utils/events.d.ts.map +1 -0
  31. package/dist/{core → utils}/events.js +26 -1
  32. package/dist/utils/helpers.d.ts +105 -20
  33. package/dist/utils/helpers.d.ts.map +1 -1
  34. package/dist/utils/helpers.js +210 -25
  35. package/package.json +12 -11
  36. package/dist/core/autoload.d.ts.map +0 -1
  37. package/dist/core/events.d.ts.map +0 -1
  38. /package/dist/{core → utils}/autoload.d.ts +0 -0
@@ -1,108 +1,61 @@
1
1
  /**
2
- @module Observables
3
-
4
-
5
- This module provides reactive data binding capabilities using observables,
6
- enabling automatic DOM updates when underlying data changes.
7
-
8
- ## Overview
9
-
10
- The observable system allows you to make object properties "observable" so that
11
- registered callbacks are automatically invoked whenever those properties change.
12
- It's particularly designed for reactive templating and binding data to HTML elements.
13
- It can also handle simple object properties like strings, boolean and numbers.
14
-
15
- ## How `observe()` Works
16
-
17
- The main function is {@link observe}, which takes an object and makes its properties
18
- or a specific property observable.
2
+ Reactive data binding via observables — object properties trigger callbacks and update
3
+ DOM placeholders automatically when their values change. Supports primitives, nested objects,
4
+ and deep-change detection with debounced notifications. Most likely you will only need the first
5
+ variant of the examples below
19
6
 
20
- ### Simple properties
7
+ @module Observables
21
8
 
22
- javascript
23
- ```js
24
- let person = { name: "John", count: 0 };
9
+ @example Plugin — chainable instance methods on DC components
10
+ ```ts
11
+ import { DC, defineCE, observePlugin } from '@twobirds/microcomponents';
25
12
 
26
- observe( person ); // all properties inside are now observables
13
+ observePlugin(DC);
27
14
 
28
- person.name.subscribe( (name) => {
29
- console.log("Name changed:", name);
30
- });
15
+ class Counter extends DC {
16
+ data = { clicks: 1 };
31
17
 
32
- person.count.subscribe( (count) => {
33
- console.log("Count changed:", count);
34
- });
18
+ oneAssets() {
19
+ this
20
+ .subscribe('data', (v) => console.log('data →', v))
21
+ .bind('data', this.target);
22
+ }
23
+ }
35
24
 
36
- person.name = "Jane"; // > Name changed: Jane
37
- person.count += 10; // > Count changed: 10
25
+ defineCE('mc-counter', Counter);
38
26
  ```
39
27
 
40
- ### Deep Change Detection
41
-
42
- This means that if you modify any of the properties inside an observed object -> all callbacks are triggered.
43
-
44
- javascript
45
- ```js
46
- let obj = { data: { name: "John", count: 0 } };
47
-
48
- observe( obj, 'data' ); // make the data property observable
49
-
50
- obj.data.subscribe( (data) => {
51
- console.log("Data changed:", data);
52
- });
28
+ @example Basic observe + subscribe on a plain object
29
+ ```ts
30
+ import { observe } from '@twobirds/microcomponents';
53
31
 
54
- obj.data.name = "Jane"; // > { data: { name: "Jane", count: 0 } }
55
- obj.data.count += 10; // > { data: { name: "Jane", count: 10 } }
32
+ const state = observe({ count: 0, label: 'hi' });
33
+ state.count.subscribe((v) => console.log('count is now', v));
34
+ state.count++; // triggers the callback
56
35
  ```
57
36
 
58
- ### Debounced Notifications
59
-
60
- To prevent excessive updates, notifications are debounced briefly:
37
+ @example Deep change detection on a nested property
38
+ ```ts
39
+ import { observe } from '@twobirds/microcomponents';
61
40
 
62
- javascript
63
- ```js
64
- let obj = observe({ value: 1 });
65
- for (let i = 0; i < 100; i++) {
66
- obj.value++; // Only triggers one callback after all changes complete
67
- }
41
+ const state = observe({ data: { name: 'John', age: 30 } });
42
+ state.data.subscribe((d) => console.log('data changed:', d));
43
+ state.data.name = 'Jane'; // triggers callback with updated object
68
44
  ```
69
45
 
70
- ## DOM Binding with Placeholders
71
-
72
- The observables integrate tightly with placeholder-based templating:
73
-
74
- - Elements with `{placeholder}` syntax are scanned for observable data.
75
- - When observed data changes, matching placeholders in the DOM are updated automatically.
76
-
77
- @example
46
+ @example DOM binding — placeholder tokens update live
47
+ ```ts
48
+ import { observe } from '@twobirds/microcomponents';
78
49
 
79
- HTML
80
- ```html
81
- <div class="model {visibility}">
82
- Hello {name}! You have {count} messages.
83
- </div>
50
+ const state = observe({ user: { name: 'Alice', count: 0 } });
51
+ state.user.bind(document.querySelector('.model'));
52
+ // <span>{user.name}</span> updates automatically when state.user.name changes
84
53
  ```
85
54
 
86
- Javascript
87
- ```js
88
- const div = document.querySelector('.model');
89
-
90
- const model = observe({
91
- data: { name: "Alice", count: 0 },
92
- visibility: ''
93
- });
94
-
95
- if (div) {
96
- model.data.bind( div );
97
- }
98
-
99
- model.data.count++; // Automatically updates the DOM with new count value
100
- model.visibility = 'hidden'; // adds the hidden class to the DOM element
101
- ```
102
55
  */
103
56
  import { flattenObject, deepEqual, copyGettersSetters, isBrowser } from '../utils/helpers.js';
104
57
  import { makePlaceholders } from './placeholders.js';
105
- import { trigger } from '../core/events.js';
58
+ import { trigger } from '../utils/events.js';
106
59
  /**
107
60
  Determines if a value is an observable object.
108
61
 
@@ -380,3 +333,90 @@ export function observe(target, propertyName) {
380
333
  });
381
334
  return target;
382
335
  }
336
+ /**
337
+ Attaches convenience methods `notify()`, `subscribe()`, and `bind()` to the prototype of a
338
+ microcomponent class so that observable properties can be controlled directly on the instance.
339
+
340
+ All three methods return the component instance, so you can chain them fluently.
341
+
342
+ Call it once at module level before defining any component classes. The plugin is idempotent —
343
+ subsequent calls are no-ops.
344
+
345
+ @param Class - A constructor function whose prototype chain includes {@link McBase}.
346
+
347
+ @example
348
+ ```ts
349
+ class Counter extends DC {
350
+ data = { clicks: 1 };
351
+
352
+ oneAssets() {
353
+ this
354
+ .subscribe('data', (v) => console.log('data →', v))
355
+ .bind('data', this.target);
356
+ }
357
+ }
358
+ ```
359
+ */
360
+ export function observePlugin(Class) {
361
+ const McBaseProto = Object.getPrototypeOf(Class.prototype);
362
+ function makePropObservable(obj, propName) {
363
+ const obs = obj[propName];
364
+ if (!isAlreadyObserved(obs)) {
365
+ observe(obj, propName);
366
+ }
367
+ }
368
+ if (!Object.hasOwn(McBaseProto, 'notify')) {
369
+ Object.assign(McBaseProto, {
370
+ /**
371
+ * Manually trigger a notification on an observable property.
372
+ * Ensures the property is observed first if it hasn't been yet.
373
+ * @param propName - The name of the observable property to notify.
374
+ * @returns This instance for chaining.
375
+
376
+ @example
377
+ ```ts
378
+ this.notify('count');
379
+ ```
380
+ */
381
+ notify: function (propName) {
382
+ makePropObservable(this, propName);
383
+ this[propName].notify();
384
+ return this; // chainable
385
+ },
386
+ /**
387
+ * Subscribe a callback to changes on an observable property.
388
+ * Ensures the property is observed first if it hasn't been yet.
389
+ * @param propName - The name of the observable property.
390
+ * @param callback - Function invoked with the new value on every change.
391
+ * @returns This instance for chaining.
392
+
393
+ @example
394
+ ```ts
395
+ this.subscribe('count', (v) => console.log('count →', v));
396
+ ```
397
+ */
398
+ subscribe: function (propName, callback) {
399
+ makePropObservable(this, propName);
400
+ this[propName].subscribe(callback);
401
+ return this; // chainable
402
+ },
403
+ /**
404
+ * Bind an observable property to a DOM target so that `{placeholder}` tokens are updated live.
405
+ * Ensures the property is observed first if it hasn't been yet.
406
+ * @param propName - The name of the observable property.
407
+ * @param target - HTMLElement, ShadowRoot, or DocumentFragment containing placeholders.
408
+ * @returns This instance for chaining.
409
+
410
+ @example
411
+ ```ts
412
+ this.bind('data', this.target);
413
+ ```
414
+ */
415
+ bind: function (propName, target) {
416
+ makePropObservable(this, propName);
417
+ this[propName].bind(target);
418
+ return this; // chainable
419
+ },
420
+ });
421
+ }
422
+ }
@@ -0,0 +1 @@
1
+ {"version":3,"file":"autoload.d.ts","sourceRoot":"","sources":["../../src/utils/autoload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;EASE;AAoJF;;;;;;;;;;;;EAYE;AACF,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;IAaG;IACH,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B;;;;;IAKG;IACH,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnB;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACpB;CACD;AAID,eAAO,MAAM,QAAQ,EAAE,QAuBtB,CAAC"}
@@ -8,8 +8,8 @@ side-effect-bearing DOM machinery (`MutationObserver`, script injection):
8
8
  importing `DC`/`MC` never pulls a DOM observer into the bundle unless
9
9
  {@link autoload} itself is imported.
10
10
  */
11
- import { DC } from './MC.js';
12
- import { isMcDOM } from './mcGuards.js';
11
+ import { DC } from '../core/MC.js';
12
+ import { isMcDOM } from '../core/mcGuards.js';
13
13
  const loadingDCs = new Set();
14
14
  /**
15
15
  Creates a closure that attaches DOM elements with the specified tag name to
@@ -57,6 +57,7 @@ off( grandParent, 'dataReady', grandParentHandler );
57
57
  ```
58
58
  */
59
59
  import type { BubbleDirections, McBubbleController, McEventHandler } from '../types/mcTypes.js';
60
+ export type { BubbleDirections } from '../types/mcTypes.js';
60
61
  /**
61
62
  * Converts a standard event name to its microcomponent-prefixed variant.
62
63
  *
@@ -71,6 +72,27 @@ import type { BubbleDirections, McBubbleController, McEventHandler } from '../ty
71
72
  * ```
72
73
  */
73
74
  export declare function getMcEventName(eventName: string): string;
75
+ /**
76
+ * Returns the correct event name to listen for on a DOM element.
77
+ *
78
+ * If `eventName` (case-insensitive) matches a native HTML event handler property
79
+ * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
80
+ * name so that standard DOM events like `'click'` are listened to correctly.
81
+ * Otherwise, prefixes with `_mc` for microcomponent custom events.
82
+ *
83
+ * @hidden
84
+ * @param target - The DOM element whose native event support is checked.
85
+ * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
86
+ * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
87
+ *
88
+ * @example
89
+ * ```ts
90
+ * const btn = document.createElement('button');
91
+ * trueEventName(btn, 'Click'); // 'click' — native handler exists
92
+ * trueEventName(btn, 'Update'); // '_mcUpdate' — custom event
93
+ * ```
94
+ */
95
+ export declare function trueEventName(target: HTMLElement, eventName: string): string;
74
96
  /**
75
97
  * A query selector string used to match one or more DOM elements.
76
98
  *
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,IAAI,CAAC;AACR,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,IAAI,CAAC;AA0BR;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,EAAE,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,OAAO,GACZ,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,CAAC,EAAE,OAAO,GACZ,kCAAkC,CAAC;AA8BtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAAC;AAsBtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,OAAO,UAAS;;IAEhB;;;;;;;;;;;;;;;OAeG;IACH,IAAI;CAGJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAClC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAW,EACjB,MAAM,GAAE,gBAAsB,EAAE,wBAAwB;AACxD,UAAU,CAAC,EAAE,gBAAgB,QA+C7B"}
@@ -57,7 +57,6 @@ off( grandParent, 'dataReady', grandParentHandler );
57
57
  ```
58
58
  */
59
59
  'use strict';
60
- import { trueEventName } from '../utils/helpers.js';
61
60
  /**
62
61
  * Converts a standard event name to its microcomponent-prefixed variant.
63
62
  *
@@ -74,6 +73,32 @@ import { trueEventName } from '../utils/helpers.js';
74
73
  export function getMcEventName(eventName) {
75
74
  return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
76
75
  }
76
+ /**
77
+ * Returns the correct event name to listen for on a DOM element.
78
+ *
79
+ * If `eventName` (case-insensitive) matches a native HTML event handler property
80
+ * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
81
+ * name so that standard DOM events like `'click'` are listened to correctly.
82
+ * Otherwise, prefixes with `_mc` for microcomponent custom events.
83
+ *
84
+ * @hidden
85
+ * @param target - The DOM element whose native event support is checked.
86
+ * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
87
+ * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
88
+ *
89
+ * @example
90
+ * ```ts
91
+ * const btn = document.createElement('button');
92
+ * trueEventName(btn, 'Click'); // 'click' — native handler exists
93
+ * trueEventName(btn, 'Update'); // '_mcUpdate' — custom event
94
+ * ```
95
+ */
96
+ export function trueEventName(target, eventName) {
97
+ const lower = eventName.toLowerCase();
98
+ if ('on' + lower in target)
99
+ return lower;
100
+ return '_mc' + eventName[0].toUpperCase() + eventName.substring(1);
101
+ }
77
102
  export function off(target, eventName, handler) {
78
103
  /* v8 ignore next */
79
104
  if (!target)
@@ -5,6 +5,7 @@ Small runtime-agnostic utilities shared across the library: environment
5
5
  detection, object flattening/comparison, debouncing, accessor copying, and
6
6
  kebab-to-PascalCase conversion.
7
7
  */
8
+ import type { McController } from '../types/mcTypes.js';
8
9
  /**
9
10
  * Determines whether the current runtime environment is a web browser.
10
11
  *
@@ -147,6 +148,7 @@ export declare function debounce<A extends unknown[]>(func: (...args: A) => unkn
147
148
  /**
148
149
  * Parses an HTML string and returns an array of DOM elements.
149
150
  * Handles self-closing tags (XHTML style) by converting them to full closing tags first.
151
+ * @hidden
150
152
  * @param html - The HTML string to parse.
151
153
  * @returns An array of HTMLElement objects representing the parsed HTML nodes.
152
154
  *
@@ -157,29 +159,10 @@ export declare function debounce<A extends unknown[]>(func: (...args: A) => unkn
157
159
  * ```
158
160
  */
159
161
  export declare function htmlToElements(html: string): HTMLElement[];
160
- /**
161
- * Returns the correct event name to listen for on a DOM element.
162
- *
163
- * If `eventName` (case-insensitive) matches a native HTML event handler property
164
- * (`'on' + eventName.toLowerCase()`) on the target, returns the lowercase native
165
- * name so that standard DOM events like `'click'` are listened to correctly.
166
- * Otherwise, prefixes with `_mc` for microcomponent custom events.
167
- *
168
- * @param target - The DOM element whose native event support is checked.
169
- * @param eventName - The event name as provided by the caller (e.g., `'click'`, `'Update'`).
170
- * @returns The resolved event name: lowercase native or `_mc`-prefixed custom.
171
- *
172
- * @example
173
- * ```ts
174
- * const btn = document.createElement('button');
175
- * trueEventName(btn, 'Click'); // 'click' — native handler exists
176
- * trueEventName(btn, 'Update'); // '_mcUpdate' — custom event
177
- * ```
178
- */
179
- export declare function trueEventName(target: HTMLElement, eventName: string): string;
180
162
  /**
181
163
  * Copies all getter and setter properties from a source object to a target object.
182
164
  * Does not copy methods or regular data properties—only accessor properties (get/set).
165
+ * @hidden
183
166
  * @param source - The source object with getters and/or setters to copy.
184
167
  * @param target - The target object to which the accessors will be copied.
185
168
  *
@@ -192,4 +175,106 @@ export declare function trueEventName(target: HTMLElement, eventName: string): s
192
175
  * ```
193
176
  */
194
177
  export declare function copyGettersSetters(source: object, target: object): void;
178
+ /**
179
+ * Injects a CSS string into the given scope (document or shadow root) as an adopted stylesheet.
180
+ * Enables css-in-js so that every custom element is self-contained and importable.
181
+ *
182
+ * @hidden
183
+ * @param target - The scope to inject styles into: `document` for global styles, or a `ShadowRoot` for encapsulated component internals.
184
+ * @param css - The CSS string to inject.
185
+ * @returns The created `CSSStyleSheet` instance that was adopted into the target scope.
186
+ *
187
+ * When targeting **document**: selectors like `:host`, `::slotted()`, and shadow-internal classes are **not allowed** — they have no effect outside a shadow root. Use only global selectors, element tags, or layout presets.
188
+ * When targeting **shadowRoot**: use `:host` for the custom element itself, standard selectors (`.inner`, `#id`) for internal structure, and `::slotted()` for projected light-DOM content.
189
+ *
190
+ * @example Inject global styles into the document:
191
+ * ```ts
192
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
193
+ * injectCSS(document, 'body { display: block; }');
194
+ * ```
195
+ *
196
+ * @example Inject global styles for a micro component into the document:
197
+ * ```ts
198
+ * import { injectCSS } from '@twobirds/mc/utils/helpers';
199
+ * injectCSS(document, 'my-microcomponent { display: block; }');
200
+ * ```
201
+ *
202
+ * @example Inject scoped styles into a shadow root:
203
+ * ```ts
204
+ * const shadow = element.attachShadow({ mode: 'open' });
205
+ * injectCSS(shadow, ':host { color: var(--text); } .inner { padding: 8px; }');
206
+ * ```
207
+ * Styles can also be added using a compound innerHTML statement: `shadow.innerHTML = \`<style>${style}</style>${template}\``
208
+ */
209
+ export declare function injectCSS(target: Document | ShadowRoot, css: string): CSSStyleSheet;
210
+ /**
211
+ * Processes a record of asset strings and applies them to the given target element.
212
+ * Supports injecting CSS into document or shadow root, and setting innerHTML for
213
+ * both target and shadow DOM. Automatically attaches a shadow root if any key starts
214
+ * with `'shadow'`.
215
+ *
216
+ * Recognized keys: `'css'`, `'targetCss'` (document-level styles), `'shadowCss'`
217
+ * (shadow-root styles), `'shadowHtml'` (shadow innerHTML), `'targetHtml'` (target innerHTML).
218
+ *
219
+ * @param target - The HTMLElement to apply assets onto.
220
+ * @param assets - A record mapping asset type keys to their string content.
221
+ *
222
+ * @example
223
+ * ```ts
224
+ * processAssets(this, {
225
+ * css: 'body { margin: 0; }',
226
+ * shadowCss: ':host { display: block; }',
227
+ * shadowHtml: '<slot></slot>'
228
+ * });
229
+ * ```
230
+ */
231
+ export declare function processAssets(instance: McController, assets: Record<string, string>): void;
232
+ /**
233
+ * Loads companion asset files (CSS, HTML) for a given component basename from the server.
234
+ *
235
+ * Each entry in `assets` encodes an optional variant and extension in camelCase, e.g. `'shadowCss'` → `{name}.shadow.css`,
236
+ * `'targetHtml'` → `{name}.target.html`. Plain entries like `'css'` or `'html'` resolve to
237
+ * `{name}.css` / `{name}.html`.
238
+ *
239
+ * In bundled mode the Vite plugin replaces this call with an inline array literal, so `.then()`
240
+ * fires synchronously — no async overhead.
241
+ *
242
+ * @hidden
243
+ * @param name - The component basename (e.g. `'shop-catalog'`).
244
+ * @param assets - Array of asset descriptors such as `'shadowCss'`, `'targetHtml'`, `'shadowHtml'`, `'css'`, `'html'`.
245
+ * @returns A promise resolving to an array of file contents in the same order as `assets`. If a file is not found, the corresponding entry is `'file not found: ' + filename`.
246
+ *
247
+ * @example
248
+ * ```ts
249
+ * export const MyComponent = loadAssets('my-component', ['shadowCss', 'shadowHtml']).then(([shadowCss, shadowHtml]) => {
250
+ * class _MyComponent extends DC { ... }
251
+ * defineCE('my-component', _MyComponent);
252
+ * return _MyComponent;
253
+ * });
254
+ * ```
255
+ */
256
+ export declare function loadAssets(name: string, assets: string[]): Promise<Array<any>>;
257
+ /**
258
+ * Binds declarative event attributes in a template fragment to microcomponent triggers.
259
+ *
260
+ * Scans all elements under `root` for attributes whose names correspond to native DOM
261
+ * events (e.g. `click`, `submit`, `change`). The attribute value encodes the target and
262
+ * handler method in the form `target|methodName`:
263
+ *
264
+ * - `this|myHandler` — triggers locally on the component attached to this element.
265
+ * - `other-comp|submit` — resolves elements via `querySelectorAll('other-comp')` and
266
+ * triggers the event on each matched host's `_mc`.
267
+ *
268
+ * An optional sibling `payload` attribute supplies the data argument for `trigger()`.
269
+ * After binding, both the event attribute and the payload attribute are removed from the DOM.
270
+ *
271
+ * @param root - The container element whose descendants should be scanned for bindings.
272
+ *
273
+ * @example
274
+ * ```html
275
+ * <button click='this|onSubmit|{"action":"go"}'>Submit</button>
276
+ * <input change="|cart-form|refresh">
277
+ * ```
278
+ */
279
+ export declare function bindTemplateEvents(rootElement: HTMLElement | ShadowRoot, instance: McController): void;
195
280
  //# sourceMappingURL=helpers.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,GAAE,MAAW,GAAG,OAAO,CAe1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,EACpD,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,OAAO,EAAE,GAChB,CAAC,CAgCH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,UAKxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC3C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC7B,YAAY,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAStB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOvE"}
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,YAAY,EAAU,MAAM,qBAAqB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,GAAG,GAAE,MAAW,GAAG,OAAO,CAe1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,EACpD,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,MAAM,EACjB,GAAG,IAAI,EAAE,OAAO,EAAE,GAChB,CAAC,CAgCH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,UAKxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAC3C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,EAC7B,YAAY,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAStB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAU1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAOnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CA4B1F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAiC9E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CA2CtG"}