@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.
- package/README.md +27 -38
- package/dist/MC.min.js +1 -1
- package/dist/autoload.min.js +1 -1
- package/dist/core/MC.d.ts +5 -2
- package/dist/core/MC.d.ts.map +1 -1
- package/dist/core/MC.js +52 -4
- package/dist/core/elements.d.ts +186 -100
- package/dist/core/elements.d.ts.map +1 -1
- package/dist/core/elements.js +186 -17
- package/dist/core/mcGuards.d.ts +1 -0
- package/dist/core/mcGuards.d.ts.map +1 -1
- package/dist/core/mcGuards.js +0 -10
- package/dist/elements.min.js +1 -1
- package/dist/events.min.js +1 -1
- package/dist/formValues.min.js +1 -1
- package/dist/microcomponents.d.ts +2 -2
- package/dist/microcomponents.d.ts.map +1 -1
- package/dist/microcomponents.js +2 -2
- package/dist/microcomponents.min.js +1 -1
- package/dist/observables.min.js +1 -1
- package/dist/state/formValues.d.ts +111 -66
- package/dist/state/formValues.d.ts.map +1 -1
- package/dist/state/formValues.js +132 -68
- package/dist/state/observables.d.ts +68 -83
- package/dist/state/observables.d.ts.map +1 -1
- package/dist/state/observables.js +124 -84
- package/dist/utils/autoload.d.ts.map +1 -0
- package/dist/{core → utils}/autoload.js +2 -2
- package/dist/{core → utils}/events.d.ts +22 -0
- package/dist/utils/events.d.ts.map +1 -0
- package/dist/{core → utils}/events.js +26 -1
- package/dist/utils/helpers.d.ts +105 -20
- package/dist/utils/helpers.d.ts.map +1 -1
- package/dist/utils/helpers.js +210 -25
- package/package.json +12 -11
- package/dist/core/autoload.d.ts.map +0 -1
- package/dist/core/events.d.ts.map +0 -1
- /package/dist/{core → utils}/autoload.d.ts +0 -0
|
@@ -1,108 +1,61 @@
|
|
|
1
1
|
/**
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
@module Observables
|
|
21
8
|
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
|
|
9
|
+
@example Plugin — chainable instance methods on DC components
|
|
10
|
+
```ts
|
|
11
|
+
import { DC, defineCE, observePlugin } from '@twobirds/microcomponents';
|
|
25
12
|
|
|
26
|
-
|
|
13
|
+
observePlugin(DC);
|
|
27
14
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
});
|
|
15
|
+
class Counter extends DC {
|
|
16
|
+
data = { clicks: 1 };
|
|
31
17
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
18
|
+
oneAssets() {
|
|
19
|
+
this
|
|
20
|
+
.subscribe('data', (v) => console.log('data →', v))
|
|
21
|
+
.bind('data', this.target);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
35
24
|
|
|
36
|
-
|
|
37
|
-
person.count += 10; // > Count changed: 10
|
|
25
|
+
defineCE('mc-counter', Counter);
|
|
38
26
|
```
|
|
39
27
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
55
|
-
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
37
|
+
@example Deep change detection on a nested property
|
|
38
|
+
```ts
|
|
39
|
+
import { observe } from '@twobirds/microcomponents';
|
|
61
40
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
<
|
|
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 '../
|
|
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 '
|
|
12
|
-
import { isMcDOM } from '
|
|
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)
|
package/dist/utils/helpers.d.ts
CHANGED
|
@@ -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
|
|
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"}
|