@symbiotejs/symbiote 3.8.1 → 3.8.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.
- package/README.md +75 -153
- package/core/webmcp.js +58 -16
- package/docs/README.md +1 -7
- package/docs/animations.md +1 -1
- package/docs/attributes.md +2 -2
- package/docs/common-mistakes.md +63 -1
- package/docs/context.md +212 -73
- package/docs/ecosystem.md +0 -3
- package/docs/llms-index.md +0 -1
- package/docs/webmcp.md +19 -0
- package/llms-full.txt +372 -230
- package/llms.txt +0 -1
- package/package.json +4 -4
- package/scripts/build-llms.js +0 -2
- package/types/core/webmcp.d.ts +2 -0
- package/types/core/webmcp.d.ts.map +1 -1
- package/CHANGELOG.md +0 -372
- package/docs/lit-vs-symbiote.md +0 -200
- package/docs/migration-2x-to-3x.md +0 -171
package/llms-full.txt
CHANGED
|
@@ -2,32 +2,36 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://rnd-pro.com/svg/symbiote/index.svg" width="200" alt="Symbiote.js">
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Symbiote.js is a lightweight, standards-first UI library built on Web Components. It extends Custom Elements with reactive data bindings, portable HTML templates, app-wide state, routing, and SSR. It works directly with browser APIs and updates bound DOM properties without virtual DOM reconciliation or excess repainting. The library has zero runtime dependencies and needs neither a compiler nor a build step. A bundler remains optional, though it is recommended for production performance.
|
|
6
6
|
|
|
7
|
-
Symbiote.js
|
|
7
|
+
## Why Symbiote.js?
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
**Runtime Agnostic Templates (RAT)** are the main reason. A Symbiote.js template is an HTML string that describes markup and named bindings. It is independent of a component instance, render function, runtime, and templating tool. You can define, customize, compose, render, and reuse it at any point in the application lifecycle, on the client or the server.
|
|
10
|
+
|
|
11
|
+
RAT keeps UI structure, data bindings, and actions declarative across client rendering, SSR, SSG, and hybrid rendering. Because the template remains a plain HTML string, a component can work beside other UI frameworks without converting its template to framework-specific syntax.
|
|
12
|
+
|
|
13
|
+
Three design choices define the library:
|
|
14
|
+
|
|
15
|
+
1. Runtime Agnostic Templates keep representation separate from component logic and make templates portable across runtimes and rendering strategies.
|
|
16
|
+
2. Direct DOM extension keeps components as real Custom Elements that standard browser APIs can inspect and control.
|
|
17
|
+
3. App-wide state connects components without prop drilling. Named contexts provide the data sources, while namespace bindings such as `APP/user` give templates and components explicit access to them.
|
|
13
18
|
|
|
14
19
|
## What's new in v3.x?
|
|
15
20
|
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- And [more](https://github.com/symbiotejs/symbiote.js/blob/webmcp/CHANGELOG.md).
|
|
21
|
+
- WebMCP support exposes live Symbiote UI actions as browser-native tools for agents, with public discovery and invocation APIs for application adapters. See the [WebMCP docs](https://github.com/symbiotejs/symbiote.js/blob/main/docs/webmcp.md).
|
|
22
|
+
- Server-side rendering uses `SSR.processHtml()` for complete HTML or `SSR.renderToStream()` for streamed chunks. On the client, `ssrMode` attaches bindings to existing DOM without rendering it again.
|
|
23
|
+
- The `isoMode` flag lets one component work in SSR and client-only scenarios without environment-specific component logic. It hydrates server-rendered content when present and otherwise renders the template from scratch.
|
|
24
|
+
- Computed properties provide reactive derived state with microtask batching.
|
|
25
|
+
- The optional `AppRouter` module supports path parameters, route guards, and lazy loading.
|
|
26
|
+
- The `animateOut(el)` helper provides CSS-driven exit transitions and integrates with the Itemize API.
|
|
27
|
+
- `Symbiote.devMode` enables verbose warnings. Import `devMessages.js` for full, human-readable messages.
|
|
28
|
+
- `ssrMode` hydrates both Light DOM and Declarative Shadow DOM.
|
|
29
|
+
- Binding keys absent from `init$` fall back to the component's own class properties and methods.
|
|
30
|
+
- The `lazyMode` flag defers component initialization and rendering until it enters the viewport. The `lazy` attribute provides the same behavior for `itemize` containers with large data sets.
|
|
27
31
|
|
|
28
32
|
## Quick start
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
Run this example directly in a browser without installing the package:
|
|
31
35
|
|
|
32
36
|
```html
|
|
33
37
|
<script type="module">
|
|
@@ -51,7 +55,7 @@ No install needed - run this directly in a browser:
|
|
|
51
55
|
<my-counter></my-counter>
|
|
52
56
|
```
|
|
53
57
|
|
|
54
|
-
|
|
58
|
+
For npm-based projects:
|
|
55
59
|
|
|
56
60
|
```bash
|
|
57
61
|
npm i @symbiotejs/symbiote
|
|
@@ -61,58 +65,26 @@ npm i @symbiotejs/symbiote
|
|
|
61
65
|
import Symbiote, { html, css } from '@symbiotejs/symbiote';
|
|
62
66
|
```
|
|
63
67
|
|
|
64
|
-
##
|
|
65
|
-
|
|
66
|
-
One component. Server-rendered or client-rendered - automatically. Set `isoMode = true` and the component figures it out: if server-rendered content exists, it hydrates; otherwise it renders from template. No conditional logic, no separate server/client versions:
|
|
67
|
-
```js
|
|
68
|
-
class MyComponent extends Symbiote {
|
|
69
|
-
isoMode = true;
|
|
70
|
-
count = 0;
|
|
71
|
-
increment() {
|
|
72
|
-
this.$.count++;
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
MyComponent.template = html`
|
|
77
|
-
<h2 ${{textContent: 'count'}}></h2>
|
|
78
|
-
<button ${{onclick: 'increment'}}>Click me!</button>
|
|
79
|
-
`;
|
|
80
|
-
MyComponent.reg('my-component');
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
This exact code runs **everywhere** - SSR on the server, hydration on the client, or pure client rendering. No framework split, no `'use client'` directives, no hydration mismatch errors.
|
|
68
|
+
## Core concepts
|
|
84
69
|
|
|
85
|
-
###
|
|
70
|
+
### Runtime Agnostic Templates (RAT)
|
|
86
71
|
|
|
87
|
-
|
|
72
|
+
A template is a plain HTML string that describes markup and named bindings. It does not run inside a component instance or close over `this`; Symbiote.js resolves the component and data context when the template is rendered or hydrated. Templates can be tested, moved between files, and reused across browser and server environments.
|
|
88
73
|
|
|
89
74
|
```js
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
await SSR.init(); // patches globals with linkedom
|
|
93
|
-
await import('./my-app.js'); // components register normally
|
|
75
|
+
// Separate file: my-component.template.js
|
|
76
|
+
import { html } from '@symbiotejs/symbiote';
|
|
94
77
|
|
|
95
|
-
|
|
96
|
-
|
|
78
|
+
export default html`
|
|
79
|
+
<h1>{{title}}</h1>
|
|
80
|
+
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
81
|
+
`;
|
|
97
82
|
```
|
|
98
83
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
### How it compares
|
|
102
|
-
|
|
103
|
-
| | **Symbiote.js** | **Next.js (React)** | **Lit** (`@lit-labs/ssr`) |
|
|
104
|
-
|--|----------------|---------------------|----|
|
|
105
|
-
| **Isomorphic code** | Same code, `isoMode` auto-detects | Server Components vs Client Components split | Same code, but load-order constraints |
|
|
106
|
-
| **Hydration** | Binding-based - attaches to existing DOM, no diffing | `hydrateRoot()` - must produce identical output or errors | Requires `ssr-client` + hydrate support module |
|
|
107
|
-
| **Packages** | 1 module + `linkedom` peer dep | Full framework buy-in | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
|
|
108
|
-
| **Streaming** | `renderToStream()` async generator | `renderToPipeableStream()` | Iterable `RenderResult` |
|
|
109
|
-
| **Mismatch handling** | Not needed - bindings attach to whatever DOM exists | Hard errors if server/client output differs | N/A |
|
|
110
|
-
| **Template output** | Clean HTML with `bind=` attributes | HTML with framework markers | HTML with `<!--lit-part-->` comment markers |
|
|
111
|
-
| **Lock-in** | None - standard Web Components | Full framework commitment | Lit-specific, but Web Components |
|
|
112
|
-
|
|
113
|
-
**Key insight:** There are no hydration mismatches because there's no diffing. The server produces HTML with binding attributes. The client reads those attributes and adds reactivity. That's it.
|
|
84
|
+
The `html` function supports two interpolation modes:
|
|
114
85
|
|
|
115
|
-
|
|
86
|
+
- An object creates a reactive binding: `${{onclick: 'handler'}}`
|
|
87
|
+
- A string or number uses native concatenation: `${pageTitle}`
|
|
116
88
|
|
|
117
89
|
### Reactive state
|
|
118
90
|
|
|
@@ -130,65 +102,37 @@ TodoItem.template = html`
|
|
|
130
102
|
`;
|
|
131
103
|
```
|
|
132
104
|
|
|
133
|
-
State changes update
|
|
105
|
+
State changes update bound DOM properties synchronously, without a virtual DOM or scheduler. Because components are real DOM elements, their state is also accessible through standard APIs:
|
|
134
106
|
|
|
135
107
|
```js
|
|
136
108
|
document.querySelector('my-counter').$.count = 42;
|
|
137
109
|
```
|
|
138
110
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
### Templates
|
|
142
|
-
|
|
143
|
-
Templates are plain HTML strings - context-free, easy to test, easy to move between files:
|
|
144
|
-
|
|
145
|
-
```js
|
|
146
|
-
// Separate file: my-component.template.js
|
|
147
|
-
import { html } from '@symbiotejs/symbiote';
|
|
148
|
-
|
|
149
|
-
export default html`
|
|
150
|
-
<h1>{{title}}</h1>
|
|
151
|
-
<button ${{onclick: 'doSomething'}}>Go</button>
|
|
152
|
-
`;
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
The `html` function supports two interpolation modes:
|
|
156
|
-
- **Object** → reactive binding: `${{onclick: 'handler'}}`
|
|
157
|
-
- **String/number** → native concatenation: `${pageTitle}`
|
|
111
|
+
Any host application can control a Symbiote.js widget or microfrontend through the DOM API. It does not need a framework adapter.
|
|
158
112
|
|
|
159
113
|
### Itemize (dynamic reactive lists)
|
|
160
114
|
|
|
161
|
-
Render lists from data arrays with efficient updates:
|
|
115
|
+
Render lists from data arrays or objects with efficient updates:
|
|
162
116
|
```js
|
|
163
117
|
class TaskList extends Symbiote {
|
|
164
118
|
tasks = [
|
|
165
119
|
{ name: 'Buy groceries' },
|
|
166
120
|
{ name: 'Write docs' },
|
|
167
121
|
];
|
|
168
|
-
init$ = {
|
|
169
|
-
// Needs to be defined in init$ for pop-up binding to work
|
|
170
|
-
onItemClick: () => {
|
|
171
|
-
console.log('clicked!');
|
|
172
|
-
},
|
|
173
|
-
}
|
|
174
122
|
}
|
|
175
123
|
|
|
176
124
|
TaskList.template = html`
|
|
177
|
-
<
|
|
125
|
+
<ul itemize="tasks">
|
|
178
126
|
<template>
|
|
179
|
-
<
|
|
127
|
+
<li>{{name}}</li>
|
|
180
128
|
</template>
|
|
181
|
-
</
|
|
129
|
+
</ul>
|
|
182
130
|
`;
|
|
183
131
|
```
|
|
184
132
|
|
|
185
|
-
Items have their own state scope. Use the **`^` prefix** to reach higher-level component properties and handlers - `'^onItemClick'` binds to the parent's `onItemClick`, not the item's. Properties referenced via `^` must be defined in the parent's `init$`.
|
|
186
|
-
|
|
187
|
-
> **Performance Tip:** For massive lists, add the `lazy` attribute to the container (`<div itemize="tasks" lazy>`). It defers component initialization until they enter the viewport and cleans them up when they leave, heavily optimizing memory and rendering performance.
|
|
188
|
-
|
|
189
133
|
### Pop-up binding (`^`)
|
|
190
134
|
|
|
191
|
-
|
|
135
|
+
In a nested component template, the `^` prefix walks up the DOM tree and finds the nearest ancestor with the requested property in its data context (`init$` or `add$()`):
|
|
192
136
|
|
|
193
137
|
```html
|
|
194
138
|
<!-- Text binding to parent property: -->
|
|
@@ -198,14 +142,12 @@ The `^` prefix works in any nested component template - it walks up the DOM tree
|
|
|
198
142
|
<button ${{onclick: '^parentHandler'}}>Click</button>
|
|
199
143
|
```
|
|
200
144
|
|
|
201
|
-
|
|
145
|
+
### Namespace bindings and named contexts
|
|
202
146
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
Share state across components without prop drilling:
|
|
147
|
+
A named context is an app-wide data source. A namespace binding such as `APP/user` gives components and templates explicit access to that source without prop drilling:
|
|
206
148
|
|
|
207
149
|
```js
|
|
208
|
-
import { PubSub } from '@symbiotejs/symbiote';
|
|
150
|
+
import { PubSub, html } from '@symbiotejs/symbiote';
|
|
209
151
|
|
|
210
152
|
PubSub.registerCtx({
|
|
211
153
|
user: 'Alex',
|
|
@@ -214,11 +156,14 @@ PubSub.registerCtx({
|
|
|
214
156
|
|
|
215
157
|
// Any component can read/write:
|
|
216
158
|
this.$['APP/user'] = 'New name';
|
|
159
|
+
|
|
160
|
+
// Any template can use property directly:
|
|
161
|
+
let template = html`<h2>{{APP/user}}</h2>`;
|
|
217
162
|
```
|
|
218
163
|
|
|
219
164
|
### Shared context (`*`)
|
|
220
165
|
|
|
221
|
-
|
|
166
|
+
Shared contexts follow the same idea as the native HTML `name` attribute used to group radio buttons. The `ctx` attribute assigns components to a shared data context, and components with the same value can use the same `*`-prefixed properties:
|
|
222
167
|
|
|
223
168
|
```html
|
|
224
169
|
<upload-btn ctx="gallery"></upload-btn>
|
|
@@ -244,13 +189,12 @@ class StatusBar extends Symbiote {
|
|
|
244
189
|
}
|
|
245
190
|
```
|
|
246
191
|
|
|
247
|
-
All three components access the same `*files` state
|
|
248
|
-
|
|
249
|
-
The context name can also be inherited via CSS custom property `--ctx`, enabling layout-driven grouping.
|
|
192
|
+
All three components access the same `*files` state. Setting `ctx="gallery"` in HTML and using `*`-prefixed properties removes the need for a parent coordinator, prop drilling, or global store boilerplate. This allows markup to describe complex relationships between reusable components that do not need direct knowledge of one another.
|
|
250
193
|
|
|
251
|
-
###
|
|
194
|
+
### Application routing
|
|
252
195
|
|
|
253
196
|
```js
|
|
197
|
+
// Import optional module:
|
|
254
198
|
import { AppRouter } from '@symbiotejs/symbiote/core/AppRouter.js';
|
|
255
199
|
|
|
256
200
|
AppRouter.initRoutingCtx('R', {
|
|
@@ -260,27 +204,11 @@ AppRouter.initRoutingCtx('R', {
|
|
|
260
204
|
});
|
|
261
205
|
```
|
|
262
206
|
|
|
263
|
-
###
|
|
264
|
-
|
|
265
|
-
CSS-driven transitions with zero JS animation code:
|
|
266
|
-
|
|
267
|
-
```css
|
|
268
|
-
task-item {
|
|
269
|
-
opacity: 1;
|
|
270
|
-
transition: opacity 0.3s;
|
|
271
|
-
|
|
272
|
-
@starting-style { opacity: 0; } /* enter */
|
|
273
|
-
&[leaving] { opacity: 0; } /* exit */
|
|
274
|
-
}
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
`animateOut(el)` sets `[leaving]`, waits for `transitionend`, then removes. Itemize uses this automatically.
|
|
207
|
+
### CSS styling
|
|
278
208
|
|
|
279
|
-
|
|
209
|
+
Shadow DOM is optional in Symbiote.js. Use it when a component needs isolation; otherwise, let the component participate in the page's regular styling.
|
|
280
210
|
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
**Light DOM** - style components with regular CSS, no barriers:
|
|
211
|
+
Light DOM components use regular CSS:
|
|
284
212
|
|
|
285
213
|
```js
|
|
286
214
|
MyComponent.rootStyles = css`
|
|
@@ -293,7 +221,9 @@ MyComponent.rootStyles = css`
|
|
|
293
221
|
`;
|
|
294
222
|
```
|
|
295
223
|
|
|
296
|
-
|
|
224
|
+
Symbiote.js applies this style to the nearest containing shadow root, when one exists, or to the document.
|
|
225
|
+
|
|
226
|
+
Use Shadow DOM for opt-in isolation:
|
|
297
227
|
|
|
298
228
|
```js
|
|
299
229
|
class Isolated extends Symbiote {}
|
|
@@ -304,11 +234,11 @@ Isolated.shadowStyles = css`
|
|
|
304
234
|
`;
|
|
305
235
|
```
|
|
306
236
|
|
|
307
|
-
|
|
237
|
+
Native CSS features remain available. CSS variables cross shadow boundaries, `::part()` exposes selected internals, and modern nesting, `@layer`, and `@container` work without framework abstractions. Light DOM and Shadow DOM components can coexist in the same application.
|
|
308
238
|
|
|
309
|
-
### CSS
|
|
239
|
+
### CSS data
|
|
310
240
|
|
|
311
|
-
Components can read CSS custom
|
|
241
|
+
Components can read CSS custom property values to initiate reactive state:
|
|
312
242
|
|
|
313
243
|
```css
|
|
314
244
|
my-widget {
|
|
@@ -324,31 +254,23 @@ MyWidget.template = html`
|
|
|
324
254
|
`;
|
|
325
255
|
```
|
|
326
256
|
|
|
327
|
-
CSS values are parsed automatically - quoted strings become strings, numbers become numbers. Call `this.updateCssData()` to re-read after runtime CSS changes. This enables CSS-driven configuration: theme values, layout parameters, or localized strings - all settable from CSS without touching JS.
|
|
328
|
-
|
|
329
257
|
## Best for
|
|
330
258
|
|
|
331
|
-
-
|
|
332
|
-
-
|
|
333
|
-
-
|
|
334
|
-
-
|
|
335
|
-
-
|
|
336
|
-
-
|
|
337
|
-
-
|
|
338
|
-
|
|
339
|
-
## Browser support
|
|
259
|
+
- Complex widgets embedded in any host application
|
|
260
|
+
- Low-code, HTML-based interfaces with declarative bindings for UI, data, and actions
|
|
261
|
+
- Microfrontends built from standard Custom Elements without framework coupling
|
|
262
|
+
- Reusable component libraries for React, Vue, Angular, or plain HTML
|
|
263
|
+
- SSR applications that need lightweight server rendering without framework lock-in
|
|
264
|
+
- Framework-agnostic solutions that reuse one codebase across contexts
|
|
265
|
+
- Agent-facing web applications that expose state and actions through WebMCP
|
|
340
266
|
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
## Docs & Examples
|
|
267
|
+
## Docs and examples
|
|
344
268
|
|
|
345
269
|
- [Documentation](https://github.com/symbiotejs/symbiote.js/blob/main/docs/README.md)
|
|
346
|
-
- [
|
|
347
|
-
- [
|
|
348
|
-
- [
|
|
349
|
-
- [
|
|
350
|
-
- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt) — complete merged reference for AI context
|
|
351
|
-
- [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
|
|
270
|
+
- [Live examples](https://rnd-pro.com/symbiote/3x/examples/): interactive code playground
|
|
271
|
+
- [JSDA-Kit](https://github.com/rnd-pro/jsda-kit): companion tooling for the server, SSG, bundling, import maps, and native Symbiote.js SSR integration
|
|
272
|
+
- [AI / llms.txt](https://rnd-pro.com/symbiote/llms.txt): index for AI tools
|
|
273
|
+
- [Full docs (single file)](https://rnd-pro.com/symbiote/llms-full.txt): complete merged reference for AI context
|
|
352
274
|
|
|
353
275
|
## Related articles
|
|
354
276
|
|
|
@@ -357,11 +279,11 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
|
|
|
357
279
|
- [Symbiote.js vs Lit](https://dev.to/foxeyes/lit-vs-symbiotejs-22gj)
|
|
358
280
|
- [JSDA Stack - A Revolutionary Simple Approach to Build Modern Web](https://dev.to/foxeyes/jsda-kit-a-revolutionary-simple-approach-to-build-modern-web-1dip)
|
|
359
281
|
|
|
360
|
-
|
|
282
|
+
Questions and proposals are welcome in [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions).
|
|
361
283
|
|
|
362
284
|
---
|
|
363
285
|
|
|
364
|
-
© [rnd-pro.com](https://rnd-pro.com)
|
|
286
|
+
© [rnd-pro.com](https://rnd-pro.com), MIT License
|
|
365
287
|
|
|
366
288
|
---
|
|
367
289
|
|
|
@@ -405,7 +327,7 @@ my-item {
|
|
|
405
327
|
|
|
406
328
|
## Itemize integration
|
|
407
329
|
|
|
408
|
-
|
|
330
|
+
Itemize processors use `animateOut` automatically for item removal. Items with CSS `transition` + `[leaving]` styles will animate out before being removed from the DOM:
|
|
409
331
|
```css
|
|
410
332
|
user-card {
|
|
411
333
|
opacity: 1;
|
|
@@ -449,7 +371,7 @@ class MyComponent extends Symbiote {}
|
|
|
449
371
|
MyComponent.template = html`<h1>{{@attribute-name}}</h1>`;
|
|
450
372
|
```
|
|
451
373
|
|
|
452
|
-
Then use it as an attribute in markup:
|
|
374
|
+
Then use it as an component's attribute in markup:
|
|
453
375
|
```html
|
|
454
376
|
<my-component attribute-name="attribute value"></my-component>
|
|
455
377
|
```
|
|
@@ -473,7 +395,7 @@ MyComponent.observedAttributes = [
|
|
|
473
395
|
|
|
474
396
|
## `bindAttributes()` static method
|
|
475
397
|
|
|
476
|
-
|
|
398
|
+
Reflect attribute values to property values:
|
|
477
399
|
```js
|
|
478
400
|
class MyComponent extends Symbiote {
|
|
479
401
|
|
|
@@ -754,7 +676,69 @@ Named external contexts (`CTX/prop`) are different: they are registered globally
|
|
|
754
676
|
|
|
755
677
|
---
|
|
756
678
|
|
|
757
|
-
## 10.
|
|
679
|
+
## 10. Using `{{prop}}` binding syntax inside tag definitions
|
|
680
|
+
|
|
681
|
+
`{{prop}}` is a **text node** binding — it only works inside element content. Any binding that targets a tag itself — attributes, DOM properties, event handlers, or CSS custom properties — must use `${{}}` or `bind=""` syntax inside the opening tag.
|
|
682
|
+
|
|
683
|
+
```html
|
|
684
|
+
<!-- WRONG — {{}} syntax does not work inside tag definitions -->
|
|
685
|
+
<div class="{{APP/theme}}">...</div>
|
|
686
|
+
<img src="{{imageUrl}}">
|
|
687
|
+
<button onclick="{{onAction}}">Go</button>
|
|
688
|
+
|
|
689
|
+
<!-- CORRECT — use ${{}} binding object inside the tag -->
|
|
690
|
+
<div ${{'@class': 'APP/theme'}}>...</div>
|
|
691
|
+
<img ${{'@src': 'imageUrl'}}>
|
|
692
|
+
<button ${{onclick: 'onAction'}}>Go</button>
|
|
693
|
+
<div ${{'style.color': 'colorProp'}}>...</div>
|
|
694
|
+
|
|
695
|
+
<!-- CORRECT — or use the bind attribute string syntax -->
|
|
696
|
+
<div bind="@class: APP/theme">...</div>
|
|
697
|
+
<img bind="@src: imageUrl">
|
|
698
|
+
<button bind="onclick: onAction">Go</button>
|
|
699
|
+
|
|
700
|
+
<!-- CORRECT — {{}} works fine in text node content -->
|
|
701
|
+
<h1>Hello, {{userName}}!</h1>
|
|
702
|
+
<p>Theme: {{APP/theme}}</p>
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
---
|
|
706
|
+
|
|
707
|
+
## 11. Expecting two-way data binding
|
|
708
|
+
|
|
709
|
+
Symbiote.js bindings are **one-way by design** — from state to DOM. There is no `v-model`, `[(ngModel)]`, or `bind:value` equivalent. To react to user input, wire the event handler explicitly and write back to state yourself.
|
|
710
|
+
|
|
711
|
+
```js
|
|
712
|
+
// WRONG — expecting the binding to also update state on user input
|
|
713
|
+
MyComponent.template = html`
|
|
714
|
+
<input ${{value: 'query'}}>
|
|
715
|
+
`;
|
|
716
|
+
|
|
717
|
+
// CORRECT — handle the input event and write back to state
|
|
718
|
+
class MyComponent extends Symbiote {
|
|
719
|
+
init$ = { query: '' }
|
|
720
|
+
}
|
|
721
|
+
|
|
722
|
+
MyComponent.template = html`
|
|
723
|
+
<input
|
|
724
|
+
${{value: 'query', oninput: 'onInput'}}
|
|
725
|
+
>
|
|
726
|
+
`;
|
|
727
|
+
```
|
|
728
|
+
```js
|
|
729
|
+
class MyComponent extends Symbiote {
|
|
730
|
+
init$ = {
|
|
731
|
+
query: '',
|
|
732
|
+
onInput: (e) => { this.$.query = e.target.value; },
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
This is intentional — explicit event handling keeps data flow predictable and avoids the hidden side effects that two-way binding can introduce.
|
|
738
|
+
|
|
739
|
+
---
|
|
740
|
+
|
|
741
|
+
## 12. Treating `init$` as a plain object
|
|
758
742
|
|
|
759
743
|
`init$` is processed once at connection time to populate the component's reactive context. Mutating it after the fact has no effect. Use `this.$` or `add$()` for runtime changes.
|
|
760
744
|
|
|
@@ -780,39 +764,46 @@ class MyComponent extends Symbiote {
|
|
|
780
764
|
|
|
781
765
|
# Context
|
|
782
766
|
|
|
783
|
-
|
|
767
|
+
Context is the central concept in Symbiote.js. Rather than passing data through prop chains or maintaining a separate global store, Symbiote uses the DOM structure itself as the data flow graph. Every component can read from and write to multiple data sources - its **context** is the union of all the sources currently accessible to it.
|
|
784
768
|
|
|
785
|
-
|
|
769
|
+
There are seven context types, each addressed by a token prefix in property keys:
|
|
770
|
+
|
|
771
|
+
| Token | Context Type | Scope |
|
|
772
|
+
|-------|-------------|-------|
|
|
773
|
+
| _(none)_ | [Local](#local-context) | Component instance |
|
|
774
|
+
| `^` | [Pop-up](#pop-up-context) | Nearest ancestor that owns the property |
|
|
775
|
+
| `*` | [Shared](#shared-context) | All components sharing a `ctx` attribute |
|
|
776
|
+
| `name/` | [Named](#named-context) | Any component, anywhere |
|
|
777
|
+
| `--` | [CSS Data](#css-data-context) | Inherited from the CSS cascade |
|
|
778
|
+
| `@` | [Attribute](./attributes.md) | HTML attribute on the element |
|
|
779
|
+
| `+` | [Computed](./properties.md#computed-properties) | Derived, auto-recalculated value |
|
|
780
|
+
|
|
781
|
+
---
|
|
786
782
|
|
|
787
783
|
## Local context
|
|
788
784
|
|
|
789
|
-
Local context
|
|
785
|
+
Local context is the component's own reactive state, scoped to the instance. It works the same way as component state in other frameworks and is invisible to other components.
|
|
786
|
+
|
|
787
|
+
Define properties in `init$`:
|
|
790
788
|
```js
|
|
791
789
|
class MyComponent extends Symbiote {
|
|
792
|
-
|
|
793
790
|
init$ = {
|
|
794
791
|
myProperty: 'some value',
|
|
795
792
|
}
|
|
796
|
-
|
|
797
793
|
}
|
|
798
794
|
```
|
|
799
795
|
|
|
800
|
-
Use the `$` proxy to read and write values:
|
|
796
|
+
Use the `$` proxy to read and write values at runtime:
|
|
801
797
|
```js
|
|
802
798
|
class MyComponent extends Symbiote {
|
|
803
|
-
|
|
804
799
|
init$ = {
|
|
805
800
|
myProperty: 'some value',
|
|
806
801
|
}
|
|
807
802
|
|
|
808
803
|
renderCallback() {
|
|
809
|
-
// Read:
|
|
810
804
|
console.log(this.$.myProperty); // > 'some value'
|
|
811
|
-
|
|
812
|
-
// Write:
|
|
813
805
|
this.$.myProperty = 'new value';
|
|
814
806
|
}
|
|
815
|
-
|
|
816
807
|
}
|
|
817
808
|
|
|
818
809
|
MyComponent.template = html`
|
|
@@ -820,97 +811,143 @@ MyComponent.template = html`
|
|
|
820
811
|
`;
|
|
821
812
|
```
|
|
822
813
|
|
|
814
|
+
For simple components without shared or computed props, you can also declare properties as plain class fields - Symbiote picks them up automatically via class-field fallback:
|
|
815
|
+
```js
|
|
816
|
+
class MyComponent extends Symbiote {
|
|
817
|
+
count = 0;
|
|
818
|
+
label = 'Hello';
|
|
819
|
+
}
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
> Use `init$` when you need shared (`*`), computed (`+`), or attribute (`@`) props in the same declaration - those tokens are only recognized inside `init$`.
|
|
823
|
+
|
|
824
|
+
See [Properties →](./properties.md) for the full property API: `add$()`, `sub()`, `set$()`, computed props, and more.
|
|
825
|
+
|
|
826
|
+
---
|
|
827
|
+
|
|
823
828
|
## Named context
|
|
824
829
|
|
|
825
|
-
Named context is
|
|
830
|
+
Named context is a global, named data store created independently of any component. Any component can read from or write to it using the `CONTEXT_NAME/property` syntax - regardless of DOM position.
|
|
826
831
|
|
|
827
|
-
|
|
832
|
+
Use named context when data must be shared across unrelated parts of the application.
|
|
833
|
+
|
|
834
|
+
**Creating a named context:**
|
|
835
|
+
```js
|
|
836
|
+
import { PubSub } from '@symbiotejs/symbiote';
|
|
837
|
+
|
|
838
|
+
let appCtx = PubSub.registerCtx({
|
|
839
|
+
theme: 'light',
|
|
840
|
+
user: null,
|
|
841
|
+
}, 'APP');
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
**Accessing it from a component:**
|
|
845
|
+
```js
|
|
846
|
+
class MyComponent extends Symbiote {
|
|
847
|
+
init$ = {
|
|
848
|
+
'APP/theme': 'light', // optional local fallback - used if the named context hasn't published yet
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
renderCallback() {
|
|
852
|
+
console.log(this.$['APP/theme']); // read
|
|
853
|
+
this.$['APP/theme'] = 'dark'; // write - updates the named context for all subscribers
|
|
854
|
+
}
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
MyComponent.template = html`
|
|
858
|
+
<div ${{'@class': 'APP/theme'}}>...</div>
|
|
859
|
+
`;
|
|
860
|
+
```
|
|
861
|
+
|
|
862
|
+
**Example - localization:**
|
|
828
863
|
```js
|
|
829
864
|
import Symbiote, { html, PubSub } from '@symbiotejs/symbiote';
|
|
830
865
|
|
|
831
|
-
|
|
832
|
-
let EN = {
|
|
866
|
+
let l10nCtx = PubSub.registerCtx({
|
|
833
867
|
users: 'Users',
|
|
834
868
|
comments: 'Comments',
|
|
835
869
|
likes: 'Likes',
|
|
836
|
-
};
|
|
837
|
-
|
|
838
|
-
// Create localization context:
|
|
839
|
-
let l10nCtx = PubSub.registerCtx(EN, 'L10N');
|
|
840
|
-
|
|
841
|
-
// Use localized strings in templates:
|
|
842
|
-
class MyComponent extends Symbiote { ... }
|
|
870
|
+
}, 'L10N');
|
|
843
871
|
|
|
844
872
|
MyComponent.template = html`
|
|
845
873
|
<div>{{L10N/users}} - {{numberOfUsers}}</div>
|
|
846
874
|
<div>{{L10N/comments}} - {{numberOfComments}}</div>
|
|
847
875
|
<div>{{L10N/likes}} - {{numberOfLikes}}</div>
|
|
848
876
|
`;
|
|
849
|
-
```
|
|
850
877
|
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
Switching language:
|
|
854
|
-
```js
|
|
855
|
-
let ES = {
|
|
878
|
+
// Switch language at any time - all subscribed components update instantly:
|
|
879
|
+
l10nCtx.multiPub({
|
|
856
880
|
users: 'Usuarios',
|
|
857
881
|
comments: 'Comentarios',
|
|
858
882
|
likes: 'Gustos',
|
|
859
|
-
};
|
|
860
|
-
|
|
861
|
-
l10nCtx.multiPub(ES);
|
|
883
|
+
});
|
|
862
884
|
```
|
|
863
885
|
|
|
864
|
-
|
|
886
|
+
You can also read and modify named context directly from any component using the `$` proxy:
|
|
865
887
|
```js
|
|
866
888
|
class MyComponent extends Symbiote {
|
|
867
889
|
renderCallback() {
|
|
868
|
-
// Read:
|
|
869
890
|
console.log(this.$['L10N/users']);
|
|
870
|
-
|
|
871
|
-
// Modify:
|
|
872
891
|
this.$['L10N/users'] = 'ユーザー';
|
|
873
892
|
}
|
|
874
893
|
}
|
|
875
894
|
```
|
|
876
895
|
|
|
877
|
-
More information about `PubSub` in the [PubSub
|
|
896
|
+
More information about `PubSub` in the [PubSub →](./pubsub.md) section.
|
|
897
|
+
|
|
898
|
+
---
|
|
878
899
|
|
|
879
900
|
## Pop-up context
|
|
880
901
|
|
|
881
|
-
Pop-up
|
|
902
|
+
Pop-up context lets a child component reach a property defined by an ancestor, without the ancestor needing to pass it down explicitly. Symbiote walks up the DOM tree until it finds a component that has the requested property in its data context.
|
|
903
|
+
|
|
904
|
+
Use the `^` token to reference a pop-up property - in both text bindings and event handlers:
|
|
905
|
+
```html
|
|
906
|
+
<!-- Text binding to ancestor property: -->
|
|
907
|
+
<div>{{^parentTitle}}</div>
|
|
908
|
+
|
|
909
|
+
<!-- Handler binding to ancestor method: -->
|
|
910
|
+
<button ${{onclick: '^onButtonClicked'}}>Click me!</button>
|
|
911
|
+
```
|
|
882
912
|
|
|
883
|
-
Use the `^` token to reference a higher-level property:
|
|
884
913
|
```js
|
|
885
|
-
class
|
|
914
|
+
class MyButton extends Symbiote {}
|
|
886
915
|
|
|
887
|
-
|
|
916
|
+
MyButton.template = html`
|
|
917
|
+
<span>{{^parentTitle}}</span>
|
|
888
918
|
<button ${{onclick: '^onButtonClicked'}}>Click me!</button>
|
|
889
919
|
`;
|
|
890
920
|
```
|
|
891
|
-
|
|
921
|
+
|
|
922
|
+
Symbiote walks up the DOM tree until it finds a component with the requested property registered in its context:
|
|
923
|
+
```js
|
|
924
|
+
class MyEditor extends Symbiote {
|
|
925
|
+
init$ = {
|
|
926
|
+
onButtonClicked: () => console.log('clicked'),
|
|
927
|
+
editorTitle: 'My Editor',
|
|
928
|
+
}
|
|
929
|
+
}
|
|
930
|
+
```
|
|
892
931
|
|
|
893
932
|
> [!IMPORTANT]
|
|
894
|
-
>
|
|
933
|
+
> Pop-up lookup only searches the **data context** (properties registered via `init$` or `add$()`). Plain class properties are not resolved this way. Always declare `^`-targeted properties in the parent's `init$`:
|
|
895
934
|
> ```js
|
|
896
935
|
> class ParentComponent extends Symbiote {
|
|
897
936
|
> init$ = {
|
|
898
|
-
> onButtonClicked: () =>
|
|
937
|
+
> onButtonClicked: () => console.log('clicked'),
|
|
899
938
|
> parentTitle: 'Hello',
|
|
900
939
|
> }
|
|
901
940
|
> }
|
|
902
941
|
> ```
|
|
903
942
|
|
|
904
|
-
|
|
943
|
+
Pop-up context is useful for composition - the same child component adapts to whichever ancestor provides the expected behavior:
|
|
905
944
|
```js
|
|
906
945
|
html`
|
|
907
946
|
<my-text-editor>
|
|
908
947
|
<complete-toolbar></complete-toolbar>
|
|
909
948
|
</my-text-editor>
|
|
910
949
|
`;
|
|
911
|
-
|
|
912
|
-
Or:
|
|
913
|
-
```js
|
|
950
|
+
// or:
|
|
914
951
|
html`
|
|
915
952
|
<my-text-editor>
|
|
916
953
|
<simplified-toolbar></simplified-toolbar>
|
|
@@ -919,19 +956,21 @@ html`
|
|
|
919
956
|
`;
|
|
920
957
|
```
|
|
921
958
|
|
|
922
|
-
> Like
|
|
959
|
+
> Like the CSS cascade, pop-up context has no collision guard. Use additional prefixes (e.g. `myApp_onSave`) in environments you don't fully control.
|
|
960
|
+
|
|
961
|
+
---
|
|
923
962
|
|
|
924
963
|
## Shared context
|
|
925
964
|
|
|
926
|
-
Shared context
|
|
965
|
+
Shared context is inspired by native HTML `name` attributes - the same way `<input name="group">` connects radio buttons into one workflow, the `ctx` attribute connects Symbiote components into a shared data context. Components with the same `ctx` name access a common reactive store with no intermediary component required.
|
|
927
966
|
|
|
928
|
-
|
|
967
|
+
**Assign a context name via the `ctx` HTML attribute:**
|
|
929
968
|
```html
|
|
930
969
|
<upload-btn ctx="gallery"></upload-btn>
|
|
931
970
|
<file-list ctx="gallery"></file-list>
|
|
932
971
|
```
|
|
933
972
|
|
|
934
|
-
Or
|
|
973
|
+
**Or via the `--ctx` CSS custom property**, which cascades like any CSS variable:
|
|
935
974
|
```css
|
|
936
975
|
.gallery-section {
|
|
937
976
|
--ctx: gallery;
|
|
@@ -945,49 +984,64 @@ Or using the `--ctx` CSS custom property:
|
|
|
945
984
|
```
|
|
946
985
|
|
|
947
986
|
The CSS approach is useful when:
|
|
948
|
-
- You want **layout-driven grouping**
|
|
949
|
-
- You need to **
|
|
950
|
-
- You work in a **framework-agnostic setup**
|
|
987
|
+
- You want **layout-driven grouping** - components inherit context from their visual container rather than repeating the attribute on each one
|
|
988
|
+
- You need to **override context at different DOM levels** - just like any CSS custom property, `--ctx` cascades and can be reassigned in nested selectors
|
|
989
|
+
- You work in a **framework-agnostic setup** - CSS context assignment is independent of the host template engine
|
|
951
990
|
|
|
952
|
-
|
|
991
|
+
**Define shared properties with the `*` token:**
|
|
953
992
|
```js
|
|
954
993
|
class UploadBtn extends Symbiote {
|
|
955
994
|
init$ = { '*files': [] }
|
|
956
995
|
|
|
957
|
-
onUpload() {
|
|
996
|
+
onUpload(newFile) {
|
|
958
997
|
this.$['*files'] = [...this.$['*files'], newFile];
|
|
959
998
|
}
|
|
960
999
|
}
|
|
961
1000
|
|
|
962
1001
|
class FileList extends Symbiote {
|
|
963
|
-
init$ = { '*files': [] } // same shared prop
|
|
1002
|
+
init$ = { '*files': [] } // same shared prop - first-registered value wins
|
|
964
1003
|
}
|
|
965
1004
|
```
|
|
966
1005
|
|
|
967
|
-
Both components
|
|
1006
|
+
Both components read and write the same `*files` store. When one updates it, the other reacts automatically - no parent component, no prop drilling, no global store.
|
|
968
1007
|
|
|
969
1008
|
### Context name resolution
|
|
970
1009
|
|
|
971
|
-
The
|
|
1010
|
+
The `ctx` name is resolved in this order (first match wins):
|
|
972
1011
|
|
|
973
|
-
1. `ctx="name"` HTML attribute
|
|
974
|
-
2. `--ctx` CSS custom property
|
|
1012
|
+
1. `ctx="name"` HTML attribute on the element
|
|
1013
|
+
2. `--ctx` CSS custom property inherited from ancestors
|
|
975
1014
|
|
|
976
|
-
> **IMPORTANT**: In 3.x, `*` properties **require** an explicit `ctx` attribute or `--ctx`
|
|
1015
|
+
> **IMPORTANT**: In Symbiote 3.x, `*` properties **require** an explicit `ctx` attribute or `--ctx` variable. Without one, no shared context is created, `*` props have no effect, and dev mode will warn (W6).
|
|
1016
|
+
|
|
1017
|
+
---
|
|
977
1018
|
|
|
978
1019
|
## CSS Data context
|
|
979
1020
|
|
|
980
|
-
Symbiote components can
|
|
981
|
-
|
|
982
|
-
:
|
|
983
|
-
|
|
984
|
-
|
|
1021
|
+
Symbiote components can initialize their properties from CSS custom property values, enabling CSS-driven configuration: theme tokens, layout parameters, or localized strings - all settable from a stylesheet without touching JavaScript.
|
|
1022
|
+
|
|
1023
|
+
Use `cssInit$` to explicitly declare CSS-initialized properties with fallback values:
|
|
1024
|
+
```js
|
|
1025
|
+
class MyWidget extends Symbiote {
|
|
1026
|
+
cssInit$ = {
|
|
1027
|
+
'--columns': 1,
|
|
1028
|
+
'--label': '',
|
|
1029
|
+
}
|
|
985
1030
|
}
|
|
1031
|
+
|
|
1032
|
+
MyWidget.template = html`
|
|
1033
|
+
<span>{{--label}}</span>
|
|
1034
|
+
`;
|
|
986
1035
|
```
|
|
987
1036
|
|
|
988
|
-
|
|
1037
|
+
```css
|
|
1038
|
+
my-widget {
|
|
1039
|
+
--columns: 3;
|
|
1040
|
+
--label: 'Click me';
|
|
1041
|
+
}
|
|
1042
|
+
```
|
|
989
1043
|
|
|
990
|
-
|
|
1044
|
+
You can also use `--` bindings directly in templates without `cssInit$`:
|
|
991
1045
|
```js
|
|
992
1046
|
class TestApp extends Symbiote {}
|
|
993
1047
|
|
|
@@ -996,10 +1050,79 @@ TestApp.template = html`
|
|
|
996
1050
|
<div>{{--text}}</div>
|
|
997
1051
|
`;
|
|
998
1052
|
```
|
|
1053
|
+
```css
|
|
1054
|
+
:root {
|
|
1055
|
+
--header: 'CSS Data';
|
|
1056
|
+
--text: 'Hello!';
|
|
1057
|
+
}
|
|
1058
|
+
```
|
|
999
1059
|
|
|
1000
|
-
> CSS custom
|
|
1060
|
+
> CSS custom property values must be valid JSON - use quoted strings (`'text'`), numbers, and `0`/`1` for booleans.
|
|
1061
|
+
|
|
1062
|
+
> CSS properties are used for **initialization only**. After the component mounts, they act as normal local context properties and no longer track CSS changes. Call `this.updateCssData()` to re-read them after runtime CSS updates.
|
|
1063
|
+
|
|
1064
|
+
Full details - `updateCssData()`, `dropCssDataCache()`, `ResizeObserver` patterns, and SSR caveats - in the [CSS Data →](./css-data.md) section.
|
|
1065
|
+
|
|
1066
|
+
---
|
|
1067
|
+
|
|
1068
|
+
## Choosing the right context type
|
|
1069
|
+
|
|
1070
|
+
| Situation | Use |
|
|
1071
|
+
|-----------|-----|
|
|
1072
|
+
| Component-local reactive state | Local - no token |
|
|
1073
|
+
| Behavior or data passed from an ancestor | Pop-up - `^` |
|
|
1074
|
+
| Sibling components sharing a workflow state | Shared - `*` |
|
|
1075
|
+
| App-wide data, accessed from anywhere in the tree | Named - `/` |
|
|
1076
|
+
| Component configured via CSS / design tokens | CSS Data - `--` |
|
|
1077
|
+
| Reacting to HTML attribute values | Attribute - `@` |
|
|
1078
|
+
| Values derived from other properties | Computed - `+` |
|
|
1079
|
+
|
|
1080
|
+
---
|
|
1081
|
+
|
|
1082
|
+
## All context types in one component
|
|
1083
|
+
|
|
1084
|
+
A concise example showing local, attribute, named, shared, and pop-up contexts working together:
|
|
1085
|
+
|
|
1086
|
+
```js
|
|
1087
|
+
import Symbiote, { html } from '@symbiotejs/symbiote';
|
|
1088
|
+
|
|
1089
|
+
class MyApp extends Symbiote {
|
|
1090
|
+
init$ = {
|
|
1091
|
+
localCtxProp: 'LOCAL',
|
|
1092
|
+
'@attr-test': '', // bound to HTML attribute
|
|
1093
|
+
'APP/namedProp': 'NAMED', // named context
|
|
1094
|
+
'*sharedProp': 'SHARED', // shared context (requires ctx="..." in HTML)
|
|
1095
|
+
}
|
|
1096
|
+
|
|
1097
|
+
onUpdate() {
|
|
1098
|
+
let suffix = ' updated';
|
|
1099
|
+
this.$.localCtxProp += suffix;
|
|
1100
|
+
this.$['APP/namedProp'] += suffix;
|
|
1101
|
+
this.$['*sharedProp'] += suffix;
|
|
1102
|
+
}
|
|
1103
|
+
}
|
|
1104
|
+
|
|
1105
|
+
MyApp.template = html`
|
|
1106
|
+
<div>local: {{localCtxProp}}</div>
|
|
1107
|
+
<div>attribute: {{@attr-test}}</div>
|
|
1108
|
+
<div>named: {{APP/namedProp}}</div>
|
|
1109
|
+
<div>shared: {{*sharedProp}}</div>
|
|
1110
|
+
<button ${{onclick: 'onUpdate'}}>Update</button>
|
|
1111
|
+
<inner-el></inner-el> <!-- reads ^localCtxProp via pop-up -->
|
|
1112
|
+
`;
|
|
1113
|
+
|
|
1114
|
+
MyApp.reg('my-app');
|
|
1001
1115
|
|
|
1002
|
-
|
|
1116
|
+
class InnerEl extends Symbiote {}
|
|
1117
|
+
InnerEl.template = html`<h2>pop-up: {{^localCtxProp}}</h2>`;
|
|
1118
|
+
InnerEl.reg('inner-el');
|
|
1119
|
+
```
|
|
1120
|
+
|
|
1121
|
+
```html
|
|
1122
|
+
<my-app attr-test="HTML value" ctx="my-ctx"></my-app>
|
|
1123
|
+
```
|
|
1124
|
+
|
|
1125
|
+
---
|
|
1003
1126
|
|
|
1004
1127
|
## Property token summary
|
|
1005
1128
|
|
|
@@ -1010,8 +1133,8 @@ More details in the [CSS Data](./css-data.md) section.
|
|
|
1010
1133
|
| `*` | Shared | `*sharedProp` |
|
|
1011
1134
|
| `/` | Named | `APP/myProp` |
|
|
1012
1135
|
| `--` | CSS Data | `--my-css-var` |
|
|
1013
|
-
| `@` | Attribute | `@my-attribute` |
|
|
1014
|
-
| `+` | Computed | `+computedProp` |
|
|
1136
|
+
| `@` | Attribute - see [Attributes →](./attributes.md) | `@my-attribute` |
|
|
1137
|
+
| `+` | Computed - see [Properties →](./properties.md#computed-properties) | `+computedProp` |
|
|
1015
1138
|
|
|
1016
1139
|
---
|
|
1017
1140
|
|
|
@@ -5282,6 +5405,25 @@ class UserCard extends Symbiote {
|
|
|
5282
5405
|
|
|
5283
5406
|
The returned text is appended to each component-owned tool description.
|
|
5284
5407
|
|
|
5408
|
+
## Direct Invocation
|
|
5409
|
+
|
|
5410
|
+
Applications can discover and invoke tools through public APIs without native browser WebMCP support:
|
|
5411
|
+
|
|
5412
|
+
```js
|
|
5413
|
+
import { getActiveWebMCPTools, executeWebMCPTool } from '@symbiotejs/symbiote/webmcp';
|
|
5414
|
+
|
|
5415
|
+
let tools = getActiveWebMCPTools();
|
|
5416
|
+
let result = await executeWebMCPTool('submit_order_in_webmcp-panel', { note: 'Ready' });
|
|
5417
|
+
```
|
|
5418
|
+
|
|
5419
|
+
Use a currently registered name from discovery. `executeWebMCPTool(name, input = {})` invokes the same executor used by native WebMCP, preserving its owner and automatic event-binding context. Synchronous handlers return their result directly; asynchronous handlers return a promise. Automatic handler responses include the state snapshot after the handler finishes.
|
|
5420
|
+
|
|
5421
|
+
Thrown errors, rejected promises, and unavailable tools return `{ isError: true, content: [{ type: 'text', text: '...' }] }`. Hidden or removed tools cannot be invoked. Calls already running are not cancelled when a tool is removed. Rediscover tools after interface changes; names identify current registrations, not permanent instances.
|
|
5422
|
+
|
|
5423
|
+
Discovery returns metadata only. `nativeActive` indicates native browser registration; a value of `false` does not prevent direct invocation. Native registration failure also leaves direct invocation available.
|
|
5424
|
+
|
|
5425
|
+
Direct invocation is an application API and does not provide browser-mediated consent or enforce native `exposedTo` restrictions. An external transport adapter is responsible for authentication, authorization, target selection, input-schema validation, and result serialization. Symbiote supplies no MCP server or transport. Native browser registration options remain unchanged.
|
|
5426
|
+
|
|
5285
5427
|
## Notes
|
|
5286
5428
|
|
|
5287
5429
|
- This is an experimental release. Names, metadata shape, and browser APIs may change.
|