@symbiotejs/symbiote 3.10.2 → 3.10.3

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 (47) hide show
  1. package/core/PubSub.js +18 -5
  2. package/core/Symbiote.js +9 -5
  3. package/core/dictionary.js +5 -22
  4. package/core/extensions.js +17 -0
  5. package/core/itemizeProcessor-keyed.js +2 -2
  6. package/core/itemizeProcessor.js +3 -3
  7. package/core/itemizeSetup.js +4 -4
  8. package/core/tpl-processors.js +17 -92
  9. package/core/webmcp-bindings.js +59 -0
  10. package/core/webmcp-dictionary.js +17 -0
  11. package/core/webmcp.js +216 -51
  12. package/docs/webmcp.md +80 -0
  13. package/html-app/BaseClass.js +2 -2
  14. package/html-app/README.md +15 -0
  15. package/html-app/actions.js +4 -2
  16. package/html-app/collection-items.js +1 -1
  17. package/html-app/examples/assets/actions.html +10 -10
  18. package/html-app/examples/assets/collections.html +19 -19
  19. package/html-app/examples/assets/components.html +1 -1
  20. package/html-app/examples/assets/conditional.html +2 -2
  21. package/html-app/examples/assets/data.html +5 -5
  22. package/html-app/examples/assets/guide.html +1 -1
  23. package/html-app/examples/assets/not-found.html +1 -1
  24. package/html-app/examples/assets/routing.html +2 -2
  25. package/html-app/examples/assets/state.html +2 -2
  26. package/html-app/examples/assets/storage.html +6 -6
  27. package/html-app/examples/full-app.html +3 -2
  28. package/package.json +13 -1
  29. package/scripts/check-html-app-size.js +2 -0
  30. package/skills/symbiote/SKILL.md +24 -1
  31. package/types/core/PubSub.d.ts.map +1 -1
  32. package/types/core/Symbiote.d.ts.map +1 -1
  33. package/types/core/dictionary.d.ts +3 -11
  34. package/types/core/extensions.d.ts +13 -0
  35. package/types/core/extensions.d.ts.map +1 -0
  36. package/types/core/itemizeSetup.d.ts +1 -1
  37. package/types/core/itemizeSetup.d.ts.map +1 -1
  38. package/types/core/tpl-processors.d.ts +0 -7
  39. package/types/core/tpl-processors.d.ts.map +1 -1
  40. package/types/core/webmcp-bindings.d.ts +18 -0
  41. package/types/core/webmcp-bindings.d.ts.map +1 -0
  42. package/types/core/webmcp-dictionary.d.ts +36 -0
  43. package/types/core/webmcp-dictionary.d.ts.map +1 -0
  44. package/types/core/webmcp.d.ts.map +1 -1
  45. package/types/html-app/actions.d.ts.map +1 -1
  46. package/types/utils/reassignDictionary.d.ts +3 -11
  47. package/types/utils/reassignDictionary.d.ts.map +1 -1
package/core/PubSub.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { DICT } from './dictionary.js';
2
+ import { extensions } from './extensions.js';
2
3
  import { warnMsg, devState } from './warn.js';
3
4
 
4
5
  // structuredClone() is limited by supported types, so we use custom cloning:
@@ -270,7 +271,9 @@ export class PubSub {
270
271
  } else {
271
272
  this.notify(prop, val);
272
273
  }
273
- globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
274
+ for (let extension of extensions.values()) {
275
+ extension.contextChanged?.(this, prop);
276
+ }
274
277
  }
275
278
 
276
279
  /**
@@ -297,7 +300,9 @@ export class PubSub {
297
300
  } else {
298
301
  this.notify(prop, val);
299
302
  }
300
- globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
303
+ for (let extension of extensions.values()) {
304
+ extension.contextChanged?.(this, prop);
305
+ }
301
306
  }
302
307
 
303
308
  /** @returns {T} */
@@ -339,7 +344,9 @@ export class PubSub {
339
344
  delete this.#externalSubs[name];
340
345
  }
341
346
  this.notify(prop, null);
342
- globalThis[DICT.MCP_PUBSUB_CHANGED_KEY]?.(this, prop);
347
+ for (let extension of extensions.values()) {
348
+ extension.contextChanged?.(this, prop);
349
+ }
343
350
  }
344
351
 
345
352
  /** @param {keyof T} prop */
@@ -430,14 +437,20 @@ export class PubSub {
430
437
  }
431
438
  }
432
439
  }
433
- globalThis[DICT.MCP_PUBSUB_REGISTERED_KEY]?.(data, uid);
440
+ for (let extension of extensions.values()) {
441
+ extension.contextRegistered?.(data, uid);
442
+ }
434
443
  return data;
435
444
  }
436
445
 
437
446
  /** @param {String | Symbol} uid */
438
447
  static deleteCtx(uid) {
439
448
  let ctx = PubSub.globalStore.get(uid);
440
- ctx && globalThis[DICT.MCP_PUBSUB_DELETED_KEY]?.(ctx, uid);
449
+ if (ctx) {
450
+ for (let extension of extensions.values()) {
451
+ extension.contextDeleted?.(ctx, uid);
452
+ }
453
+ }
441
454
  PubSub.globalStore.delete(uid);
442
455
  }
443
456
 
package/core/Symbiote.js CHANGED
@@ -5,6 +5,7 @@ import { animateOut } from './animateOut.js';
5
5
  import { setNestedProp } from '../utils/setNestedProp.js';
6
6
  import { prepareStyleSheet } from '../utils/prepareStyleSheet.js';
7
7
  import { parseProp } from './parseProp.js';
8
+ import { extensions } from './extensions.js';
8
9
 
9
10
  import PROCESSORS from './tpl-processors.js';
10
11
  import { resolveTemplate } from './resolveTemplate.js';
@@ -88,7 +89,9 @@ export class Symbiote extends HTMLElement {
88
89
  * @param {Boolean} [shadow]
89
90
  */
90
91
  render(template, shadow = this.renderShadow) {
91
- this[DICT.MCP_EVENTS_KEY] = [];
92
+ for (let extension of extensions.values()) {
93
+ extension.beforeRender?.(this);
94
+ }
92
95
  /** @type {DocumentFragment} */
93
96
  let fr;
94
97
  if ((shadow || this.#super.shadowStyleSheets) && !this.shadowRoot) {
@@ -209,15 +212,16 @@ export class Symbiote extends HTMLElement {
209
212
 
210
213
  syncWebMCPTools() {
211
214
  if (globalThis.__SYMBIOTE_SSR) return;
212
- let sync = globalThis[DICT.MCP_SYNC_OWNER_KEY];
213
- if (sync) {
214
- sync(this);
215
+ for (let extension of extensions.values()) {
216
+ extension.syncOwner?.(this);
215
217
  }
216
218
  }
217
219
 
218
220
  unregisterWebMCPTools() {
219
221
  if (globalThis.__SYMBIOTE_SSR) return;
220
- globalThis[DICT.MCP_UNREGISTER_OWNER_KEY]?.(this);
222
+ for (let extension of extensions.values()) {
223
+ extension.disconnectOwner?.(this);
224
+ }
221
225
  }
222
226
 
223
227
  /** @returns {String} */
@@ -37,26 +37,9 @@ export const DICT = {
37
37
  TEXT_NODE_OPEN_TOKEN: '{{',
38
38
  // Text node binding token:
39
39
  TEXT_NODE_CLOSE_TOKEN: '}}',
40
- // WebMCP component event handler metadata key:
41
- MCP_EVENTS_KEY: '__symbioteMcpEventHandlers',
42
- // WebMCP ToolDescriptor marker key:
43
- MCP_TOOL_DESCRIPTOR_MARKER: '__symbioteToolDescriptor',
44
- // WebMCP owner id metadata key:
45
- MCP_OWNER_ID_KEY: '__symbioteMcpOwnerId',
46
- // WebMCP global hook for owner sync:
47
- MCP_SYNC_OWNER_KEY: '__SYMBIOTE_WEBMCP_SYNC_OWNER',
48
- // WebMCP global hook for owner cleanup:
49
- MCP_UNREGISTER_OWNER_KEY: '__SYMBIOTE_WEBMCP_UNREGISTER_OWNER',
50
- // WebMCP global hook for PubSub context registration:
51
- MCP_PUBSUB_REGISTERED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_REGISTERED',
52
- // WebMCP global hook for PubSub context deletion:
53
- MCP_PUBSUB_DELETED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_DELETED',
54
- // WebMCP global hook for PubSub property changes:
55
- MCP_PUBSUB_CHANGED_KEY: '__SYMBIOTE_WEBMCP_PUBSUB_CHANGED',
56
- // WebMCP itemize item visible index metadata key:
57
- MCP_ITEM_INDEX_KEY: '__symbioteMcpItemIndex',
58
- // WebMCP itemize item stable key metadata key:
59
- MCP_ITEM_KEY_KEY: '__symbioteMcpItemKey',
60
- // WebMCP forwarded event target owners metadata key:
61
- MCP_EVENT_TARGET_OWNERS_KEY: '__symbioteMcpEventTargetOwners',
40
+ // Framework-generated state handler marker:
41
+ GENERATED_HANDLER_KEY: '__symbioteGeneratedHandler',
42
+ // Itemize item index and stable identity:
43
+ ITEM_INDEX_KEY: '__symbioteItemIndex',
44
+ ITEM_KEY_KEY: '__symbioteItemKey',
62
45
  };
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Optional integrations register hooks without importing their implementation
3
+ * into the core binding, component, or context modules.
4
+ * @typedef {Object} Extension
5
+ * @property {(owner: any) => void} [beforeRender]
6
+ * @property {(owner: any) => void} [syncOwner]
7
+ * @property {(owner: any) => void} [disconnectOwner]
8
+ * @property {(owner: any, prop: string, key: string, el: Element) => void} [binding]
9
+ * @property {(value: any, owner: any, prop: string) => any} [bindingValue]
10
+ * @property {(owner: any) => boolean} [preserveBindings]
11
+ * @property {(ctx: any, uid: string | Symbol) => void} [contextRegistered]
12
+ * @property {(ctx: any, uid: string | Symbol) => void} [contextDeleted]
13
+ * @property {(ctx: any, prop: any) => void} [contextChanged]
14
+ */
15
+
16
+ /** @type {Map<string, Extension>} */
17
+ export const extensions = new Map();
@@ -1,6 +1,6 @@
1
1
  import { animateOut } from './animateOut.js';
2
2
  import { warnMsg } from './warn.js';
3
- import { setupItemize, setItemWebMCPMetadata } from './itemizeSetup.js';
3
+ import { setupItemize, setItemMetadata } from './itemizeSetup.js';
4
4
 
5
5
  /**
6
6
  * Optional Itemize processor with stable keyed identity.
@@ -80,7 +80,7 @@ export function itemizeProcessor(fr, fnCtx) {
80
80
  }
81
81
  Object.assign(child.init$ || child, item);
82
82
  }
83
- setItemWebMCPMetadata(child, item, index, keyProp ? item[keyProp] : undefined);
83
+ setItemMetadata(child, item, index, keyProp ? item[keyProp] : undefined);
84
84
  return child;
85
85
  });
86
86
  // Leaving elements are excluded from future reconciliation immediately.
@@ -1,6 +1,6 @@
1
1
  import { animateOut } from './animateOut.js';
2
2
  import { warnMsg } from './warn.js';
3
- import { setupItemize, setItemWebMCPMetadata } from './itemizeSetup.js';
3
+ import { setupItemize, setItemMetadata } from './itemizeSetup.js';
4
4
 
5
5
  /**
6
6
  * @template {import('./Symbiote.js').Symbiote} T
@@ -22,7 +22,7 @@ export function itemizeProcessor(fr, fnCtx) {
22
22
  let fillItems = (/** @type {*[]} */ items) => {
23
23
  items.forEach((item, idx) => {
24
24
  if (currentList[idx]) {
25
- setItemWebMCPMetadata(currentList[idx], item, idx);
25
+ setItemMetadata(currentList[idx], item, idx);
26
26
  if (currentList[idx].set$) {
27
27
  currentList[idx].set$(item);
28
28
  } else {
@@ -38,7 +38,7 @@ export function itemizeProcessor(fr, fnCtx) {
38
38
  if (isLazy) {
39
39
  repeatItem.lazyMode = true;
40
40
  }
41
- setItemWebMCPMetadata(repeatItem, item, idx);
41
+ setItemMetadata(repeatItem, item, idx);
42
42
  Object.assign((repeatItem?.init$ || repeatItem), item);
43
43
  fragment.appendChild(repeatItem);
44
44
  }
@@ -10,13 +10,13 @@ import { warnMsg } from './warn.js';
10
10
  * @param {number} idx
11
11
  * @param {unknown} [key]
12
12
  */
13
- export function setItemWebMCPMetadata(itemEl, item, idx, key = item && Object.hasOwn(item, '_KEY_') ? item._KEY_ : undefined) {
13
+ export function setItemMetadata(itemEl, item, idx, key = item && Object.hasOwn(item, '_KEY_') ? item._KEY_ : undefined) {
14
14
  if (!itemEl) { return; }
15
- itemEl[DICT.MCP_ITEM_INDEX_KEY] = idx;
15
+ itemEl[DICT.ITEM_INDEX_KEY] = idx;
16
16
  if (key !== undefined) {
17
- itemEl[DICT.MCP_ITEM_KEY_KEY] = key;
17
+ itemEl[DICT.ITEM_KEY_KEY] = key;
18
18
  } else {
19
- delete itemEl[DICT.MCP_ITEM_KEY_KEY];
19
+ delete itemEl[DICT.ITEM_KEY_KEY];
20
20
  }
21
21
  }
22
22
 
@@ -3,99 +3,13 @@ import { warnMsg, devState } from './warn.js';
3
3
  import { setNestedProp } from '../utils/setNestedProp.js';
4
4
  import { ownElements, isOwnNode } from './ownElements.js';
5
5
  import { initPropFallback } from './initPropFallback.js';
6
- import { parseProp } from './parseProp.js';
6
+ import { extensions } from './extensions.js';
7
7
 
8
8
  // Should go first among other processors:
9
9
  import { itemizeProcessor } from './itemizeProcessor.js';
10
10
 
11
11
  export { initPropFallback };
12
12
 
13
- /**
14
- * @typedef {Object} MCPEventBinding
15
- * @property {string} prop
16
- * @property {string} key
17
- * @property {Element} el
18
- * @property {string} [sourceKey]
19
- * @property {import('./Symbiote.js').Symbiote} [sourceOwner]
20
- */
21
-
22
- /**
23
- * @template {import('./Symbiote.js').Symbiote} T
24
- * @param {T} fnCtx
25
- * @returns {boolean}
26
- */
27
- function mcpToolMode(fnCtx) {
28
- return !!(fnCtx.mcpToolMode || /** @type {any} */ (fnCtx.constructor)?.mcpToolMode);
29
- }
30
-
31
- /**
32
- * @param {any} val
33
- * @returns {boolean}
34
- */
35
- function isToolDescriptor(val) {
36
- return !!val?.[DICT.MCP_TOOL_DESCRIPTOR_MARKER];
37
- }
38
-
39
- /**
40
- * @param {import('./Symbiote.js').Symbiote} owner
41
- * @param {MCPEventBinding} entry
42
- */
43
- function addMcpEventHandler(owner, entry) {
44
- if (!owner[DICT.MCP_EVENTS_KEY]) {
45
- owner[DICT.MCP_EVENTS_KEY] = [];
46
- }
47
- let exists = owner[DICT.MCP_EVENTS_KEY].some((item) => {
48
- return item.prop === entry.prop && item.key === entry.key && item.el === entry.el
49
- && item.sourceOwner === entry.sourceOwner;
50
- });
51
- if (!exists) {
52
- owner[DICT.MCP_EVENTS_KEY].push(entry);
53
- }
54
- }
55
-
56
- /**
57
- * @template {import('./Symbiote.js').Symbiote} T
58
- * @param {T} fnCtx
59
- * @param {string} prop
60
- * @param {string} valKey
61
- * @param {Element} el
62
- */
63
- function collectMcpEventHandler(fnCtx, prop, valKey, el) {
64
- if (!mcpToolMode(fnCtx) && !isToolDescriptor(fnCtx.$?.[valKey])) {
65
- return;
66
- }
67
- if (!prop.startsWith('on')) {
68
- return;
69
- }
70
- addMcpEventHandler(fnCtx, {
71
- prop,
72
- key: valKey,
73
- el,
74
- });
75
- if (valKey.startsWith(DICT.PARENT_CTX_PX)) {
76
- let parsed = parseProp(valKey, fnCtx);
77
- let key = parsed?.name || valKey.slice(DICT.PARENT_CTX_PX.length);
78
- let targetOwner = parsed?.scope === 'parent' && parsed.owner !== fnCtx
79
- ? parsed.owner
80
- : null;
81
- if (targetOwner && mcpToolMode(targetOwner)) {
82
- addMcpEventHandler(targetOwner, {
83
- prop,
84
- key,
85
- el,
86
- sourceKey: valKey,
87
- sourceOwner: fnCtx,
88
- });
89
- if (!fnCtx[DICT.MCP_EVENT_TARGET_OWNERS_KEY]) {
90
- fnCtx[DICT.MCP_EVENT_TARGET_OWNERS_KEY] = new Set();
91
- }
92
- fnCtx[DICT.MCP_EVENT_TARGET_OWNERS_KEY].add(targetOwner);
93
- targetOwner.syncWebMCPTools?.();
94
- }
95
- }
96
- }
97
-
98
-
99
13
  /**
100
14
  * @template {import('./Symbiote.js').Symbiote} T
101
15
  * @param {DocumentFragment} fr
@@ -154,14 +68,21 @@ function domBindProcessor(fr, fnCtx) {
154
68
  warnMsg(11, fnCtx.localName, valKey, known.join(', '));
155
69
  }
156
70
  }
157
- collectMcpEventHandler(fnCtx, prop, valKey, el);
71
+ if (!isAttr && !castType) {
72
+ for (let extension of extensions.values()) {
73
+ extension.binding?.(fnCtx, prop, valKey, el);
74
+ }
75
+ }
158
76
  let initVal = fnCtx.$[valKey];
159
77
  let skipInit = fnCtx.ssrMode && !globalThis.__SYMBIOTE_SSR
160
78
  && (isAttr || (typeof initVal !== 'function' && (initVal === null || typeof initVal !== 'object')));
161
79
  fnCtx.sub(valKey, (val) => {
162
- if (!isAttr && prop.startsWith('on') && isToolDescriptor(val)) {
163
- let descriptor = val;
164
- val = (event) => descriptor.execute({}, fnCtx, event);
80
+ if (!isAttr) {
81
+ for (let extension of extensions.values()) {
82
+ if (extension.bindingValue) {
83
+ val = extension.bindingValue(val, fnCtx, prop);
84
+ }
85
+ }
165
86
  }
166
87
  if (castType === 'double') {
167
88
  val = !!val;
@@ -190,7 +111,11 @@ function domBindProcessor(fr, fnCtx) {
190
111
  }, !skipInit);
191
112
  }
192
113
  });
193
- if (!globalThis.__SYMBIOTE_SSR && !mcpToolMode(fnCtx)) {
114
+ let preserveBindings = false;
115
+ for (let extension of extensions.values()) {
116
+ preserveBindings ||= !!extension.preserveBindings?.(fnCtx);
117
+ }
118
+ if (!globalThis.__SYMBIOTE_SSR && !preserveBindings) {
194
119
  el.removeAttribute(DICT.BIND_ATTR);
195
120
  }
196
121
  });
@@ -0,0 +1,59 @@
1
+ import { DICT } from './dictionary.js';
2
+ import { parseProp } from './parseProp.js';
3
+ import { WEBMCP_DICT as MCP } from './webmcp-dictionary.js';
4
+
5
+ /**
6
+ * @typedef {Object} MCPEventBinding
7
+ * @property {string} prop
8
+ * @property {string} key
9
+ * @property {Element} el
10
+ * @property {string} [sourceKey]
11
+ * @property {import('./Symbiote.js').Symbiote} [sourceOwner]
12
+ */
13
+
14
+ export function isToolDescriptor(value) {
15
+ return !!value?.[MCP.TOOL_DESCRIPTOR_MARKER];
16
+ }
17
+
18
+ function mcpToolMode(owner) {
19
+ return !!(owner.mcpToolMode || owner.constructor?.mcpToolMode);
20
+ }
21
+
22
+ /** @param {any} owner @param {MCPEventBinding} entry */
23
+ function addMcpEventHandler(owner, entry) {
24
+ let handlers = owner[MCP.EVENTS_KEY] ||= [];
25
+ if (!handlers.some((item) => item.prop === entry.prop && item.key === entry.key
26
+ && item.el === entry.el && item.sourceOwner === entry.sourceOwner)) {
27
+ handlers.push(entry);
28
+ }
29
+ }
30
+
31
+ function collectMcpEventHandler(owner, prop, key, el) {
32
+ if (globalThis.__SYMBIOTE_SSR || !Object.hasOwn(MCP.TOOL_EVENTS, prop)
33
+ || (!mcpToolMode(owner) && !isToolDescriptor(owner.$?.[key]))) {
34
+ return;
35
+ }
36
+ addMcpEventHandler(owner, { prop, key, el });
37
+ if (key.startsWith(DICT.PARENT_CTX_PX)) {
38
+ let parsed = parseProp(key, owner);
39
+ let target = parsed?.scope === 'parent' && parsed.owner !== owner ? parsed.owner : null;
40
+ if (target && mcpToolMode(target)) {
41
+ addMcpEventHandler(target, { prop, key: parsed.name, el, sourceKey: key, sourceOwner: owner });
42
+ (owner[MCP.EVENT_TARGET_OWNERS_KEY] ||= new Set()).add(target);
43
+ target.syncWebMCPTools?.();
44
+ }
45
+ }
46
+ }
47
+
48
+ export const webMCPBindings = {
49
+ beforeRender(owner) {
50
+ owner[MCP.EVENTS_KEY] = [];
51
+ },
52
+ binding: collectMcpEventHandler,
53
+ bindingValue(value, owner, prop) {
54
+ return prop.startsWith('on') && isToolDescriptor(value)
55
+ ? (event) => value.execute({}, owner, event)
56
+ : value;
57
+ },
58
+ preserveBindings: mcpToolMode,
59
+ };
@@ -0,0 +1,17 @@
1
+ export const WEBMCP_DICT = {
2
+ TOOL_NAME_ATTR: 'toolname',
3
+ TOOL_DESCRIPTION_ATTR: 'tooldescription',
4
+ TOOL_AUTOSUBMIT_ATTR: 'toolautosubmit',
5
+ TOOL_EVENTS: {
6
+ onclick: { event: 'click', description: 'Activate control' },
7
+ onsubmit: { event: 'submit', description: 'Submit form' },
8
+ onchange: { event: 'change', description: 'Commit control value or selection' },
9
+ oninput: { event: 'input', description: 'Insert data into control' },
10
+ },
11
+ EVENTS_KEY: '__symbioteMcpEventHandlers',
12
+ TOOL_DESCRIPTOR_MARKER: '__symbioteToolDescriptor',
13
+ OWNER_ID_KEY: '__symbioteMcpOwnerId',
14
+ SYNC_OWNER_KEY: '__SYMBIOTE_WEBMCP_SYNC_OWNER',
15
+ UNREGISTER_OWNER_KEY: '__SYMBIOTE_WEBMCP_UNREGISTER_OWNER',
16
+ EVENT_TARGET_OWNERS_KEY: '__symbioteMcpEventTargetOwners',
17
+ };