@symbiotejs/symbiote 3.0.5 → 3.1.2

package/AI_REFERENCE.md

@@ -1,7 +1,7 @@
 # Symbiote.js — AI Context Reference (v3.x)
 
 > **Purpose**: Authoritative reference for AI code assistants. All information is derived from source code analysis of [symbiote.js](https://github.com/symbiotejs/symbiote.js).
-> Current version: **3.0.0-rc.1**. Zero dependencies. ~6 KB gzip.
+> Current version: **3.1.0**. Zero dependencies. ~6 KB gzip.
 
 ---
 
@@ -33,25 +33,13 @@ Symbiote extends `HTMLElement`. Every component is a Custom Element.
 
 ```js
 class MyComponent extends Symbiote {
-  // Initial reactive state (key-value pairs)
-  init$ = {
-    name: 'World',
-    count: 0,
-    onBtnClick: () => {
-      this.$.count++;
-    },
-  };
-
-  // Called once after init$ is processed but BEFORE template is rendered
-  initCallback() {}
+  // Class properties as initial values (fallback)
+  name = 'World';
+  count = 0;
 
-  // Called once AFTER template is rendered and attached to DOM
-  renderCallback() {
-    // Safe to access this.ref, this.$, DOM children here
+  onBtnClick() {
+    this.$.count++;
   }
-
-  // Called when element is disconnected and readyToDestroy is true
-  destroyCallback() {}
 }
 
 // Template — assigned via static property SETTER, outside the class body
@@ -70,6 +58,13 @@ MyComponent.reg('my-component');
 > Using `static template = html\`...\`` inside the class declaration **will NOT work**.
 > Templates are plain HTML strings, NOT JSX. Use the `html` tagged template literal.
 
+### Lifecycle callbacks (override in subclass)
+| Method | When called |
+|--------|------------|
+| `initCallback()` | Once, after state initialized, before render (if `pauseRender=true`) or normally after render |
+| `renderCallback()` | Once, after template is rendered and attached to DOM |
+| `destroyCallback()` | On disconnect, after 100ms delay, only if `readyToDestroy=true` |
+
 ### Usage in HTML
 ```html
 <my-component></my-component>
@@ -95,21 +90,24 @@ Binds `propName` from component state to the text content of a text node. Works
 ### Property binding (element's own properties)
 ```html
 <button ${{onclick: 'handlerName'}}>Click</button>
-<div ${{textContent: 'myProp'}}></div>
+<div>{{myProp}}</div>
 ```
 The `${{key: 'value'}}` interpolation creates a `bind="key:value;"` attribute. Keys are DOM element property names. Values are component state property names (strings).
 
-**Event handler resolution (3.x):** For `on*` bindings, Symbiote first looks for the key in `init$` (reactive state). If not found, it falls back to a **class method** with the same name. Both approaches work:
+**Class property fallback (3.x):** For any binding key not found in `init$`, Symbiote checks own instance properties first (`Object.hasOwn` — safe from inherited `HTMLElement` collisions), then prototype methods. Functions are automatically `.bind()`-ed to the component instance:
 ```js
 class MyComp extends Symbiote {
-  // Approach 1: state property (arrow function)
-  init$ = { onClick: () => console.log('clicked') };
+  // Approach 1: state property in init$
+  init$ = { count: 0 };
 
-  // Approach 2: class method (fallback)
+  // Approach 2: class property / method (fallback)
+  label = 'Click me';
   onSubmit() { console.log('submitted'); }
 }
 ```
 
+> **Recommendation:** Use class property fallback for **simple components** — keeps code compact. For **complex components** with many reactive properties, prefer `init$` to explicitly separate reactive state from regular class properties.
+
 ### Nested property binding
 ```html
 <div ${{'style.color': 'colorProp'}}>Text</div>
@@ -155,16 +153,16 @@ Prefixes control which data context a binding resolves to:
 | `^` | Parent inherited | `{{^parentProp}}` | Walk up DOM ancestry to find nearest component that has this prop |
 | `*` | Shared context | `{{*sharedProp}}` | Shared context scoped by `ctx` attribute or CSS `--ctx` |
 | `/` | Named context | `{{APP/myProp}}` | Global named context identified by key before `/` |
-| `--` | CSS Data | `${{textContent: '--my-css-var'}}` | Read value from CSS custom property |
+| `--` | CSS Data | `{{--my-css-var}}` | Read value from CSS custom property |
 | `+` | Computed | (in init$) `'+sum': () => ...` | Function recalculated when local dependencies change (auto-tracked) |
 
 ### Examples in init$
 ```js
 init$ = {
-  localProp: 'hello',           // local
-  '*sharedProp': 'shared value', // shared context
-  'APP/globalProp': 42,          // named context "APP"
-  '+computed': () => this.$.a + this.$.b, // local computed (auto-tracked)
+  localProp: 'hello',           // local (prefer class properties for simple cases)
+  '*sharedProp': 'shared value', // shared context (requires init$)
+  'APP/globalProp': 42,          // named context (requires init$)
+  '+computed': () => this.$.a + this.$.b, // local computed (requires init$)
 };
 ```
 
@@ -277,18 +275,15 @@ Components grouped by the `ctx` HTML attribute (or `--ctx` CSS custom property)
 
 ```js
 class UploadBtn extends Symbiote {
-  init$ = {
-    '*files': [],
-    onUpload: () => {
-      this.$['*files'] = [...this.$['*files'], newFile];
-    },
+  init$ = { '*files': [] }
+
+  onUpload() {
+    this.$['*files'] = [...this.$['*files'], newFile];
   }
 }
 
 class FileList extends Symbiote {
-  init$ = {
-    '*files': [],  // same shared prop — first-registered value wins
-  }
+  init$ = { '*files': [] }  // same shared prop — first-registered value wins
 }
 ```
 
@@ -434,10 +429,11 @@ class MyList extends Symbiote {
       { name: 'Alice', role: 'Admin' },
       { name: 'Bob', role: 'User' },
     ],
-    onItemClick: (e) => {
-      console.log('clicked');
-    },
-  };
+  }
+
+  onItemClick(e) {
+    console.log('clicked');
+  }
 }
 
 MyList.template = html`
@@ -710,7 +706,7 @@ class MyComponent extends Symbiote {
 
 Or in template:
 ```html
-<div ${{textContent: '--my-css-prop'}}>...</div>
+<div>{{--my-css-prop}}</div>
 ```
 
 Update with: `this.updateCssData()` / `this.dropCssDataCache()`.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.1.0
+
+### Changed
+
+- **Class property fallback (generalized).**
+  Bindings not found in `init$` now fall back to own class properties (checked via `Object.hasOwn`), not just `on*` event handlers. Functions are auto-bound to the component instance. Inherited `HTMLElement` properties are never picked up.
+  ```js
+  class MyComp extends Symbiote {
+    label = 'Click me';
+    onSubmit() { console.log('submitted'); }
+  }
+  ```
+  Previously only `on*` handlers supported this fallback.
+
 ## 3.0.0
 
 ### ⚠️ Breaking Changes
@@ -128,9 +142,10 @@
   { pattern: '/settings', load: () => import('./pages/settings.js') }
   ```
 
-- **Event handler method fallback.**
-  `on*` bindings fall back to class methods when no `init$` property found:
+- **Class property fallback.**
+  Bindings not in `init$` fall back to own class properties/methods:
   ```js
+  label = 'Click me';
   onSubmit() { console.log('submitted'); }
   ```
 

package/README.md

@@ -17,7 +17,7 @@ Symbiote.js gives you the convenience of a modern framework while staying close
 - **Exit animations** — `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
 - **Dev mode** — `Symbiote.devMode` enables verbose warnings for unresolved bindings.
 - **DSD hydration** — `ssrMode` supports both light DOM and Declarative Shadow DOM.
-- **on-event-handlers fallback** — event handlers now able to be described as direct class methods.
+- **Class property fallback** — binding keys not in `init$` fall back to own class properties/methods.
 - And [more](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md).
 
 ## Quick start
@@ -29,11 +29,9 @@ No install needed — run this directly in a browser:
   import Symbiote, { html } from 'https://esm.run/@symbiotejs/symbiote';
 
   class MyCounter extends Symbiote {
-    init$ = {
-      count: 0,
-      increment: () => {
-        this.$.count++;
-      },
+    count = 0;
+    increment() {
+      this.$.count++;
     }
   }
 
@@ -116,12 +114,10 @@ http.createServer(async (req, res) => {
 
 ```js
 class TodoItem extends Symbiote {
-  init$ = {
-    text: '',
-    done: false,
-    toggle: () => {
-      this.$.done = !this.$.done;
-    },
+  text = '';
+  done = false;
+  toggle() {
+    this.$.done = !this.$.done;
   }
 }
 
@@ -153,7 +149,7 @@ export default html`
 ```
 
 The `html` function supports two interpolation modes:
-- **Object** → reactive binding: `${{textContent: 'myProp'}}`
+- **Object** → reactive binding: `${{onclick: 'handler'}}`
 - **String/number** → native concatenation: `${pageTitle}`
 
 ### Itemize (lists)
@@ -167,9 +163,10 @@ class TaskList extends Symbiote {
       { name: 'Buy groceries' },
       { name: 'Write docs' },
     ],
-    onItemClick: () => {
-      console.log('clicked!');
-    },
+  }
+
+  onItemClick() {
+    console.log('clicked!');
   }
 }
 
@@ -224,25 +221,19 @@ Inspired by native HTML `name` attributes — like how `<input name="group">` gr
 
 ```js
 class UploadBtn extends Symbiote {
-  init$ = {
-    '*files': [],
-    onUpload: () => {
-      ...
-      this.$['*files'] = [...this.$['*files'], newFile];
-    },
+  init$ = { '*files': [] }
+
+  onUpload() {
+    this.$['*files'] = [...this.$['*files'], newFile];
   }
 }
 
 class FileList extends Symbiote {
-  init$ = {
-    '*files': [],
-  }
+  init$ = { '*files': [] }
 }
 
 class StatusBar extends Symbiote {
-  init$ = {
-    '*files': [],
-  }
+  init$ = { '*files': [] }
 }
 ```
 
@@ -328,7 +319,7 @@ class MyWidget extends Symbiote {
 }
 
 MyWidget.template = html`
-  <span ${{textContent: '--label'}}></span>
+  <span>{{--label}}</span>
 `;
 ```
 

package/core/itemizeProcessor.js

@@ -32,6 +32,11 @@ export function itemizeProcessor(fr, fnCtx) {
         el.firstChild.remove();
       }
       let repeatDataKey = el.getAttribute(DICT.LIST_ATTR);
+      if (!fnCtx.has(repeatDataKey) && fnCtx.allowTemplateInits) {
+        if (Object.hasOwn(fnCtx, repeatDataKey) && fnCtx[repeatDataKey] !== undefined) {
+          fnCtx.add(repeatDataKey, fnCtx[repeatDataKey]);
+        }
+      }
       fnCtx.sub(repeatDataKey, (data) => {
         if (!data) {
           while (el.firstChild) {

package/core/tpl-processors.js

@@ -60,10 +60,15 @@ function domBindProcessor(fr, fnCtx) {
         if (!fnCtx.has(valKey) && fnCtx.allowTemplateInits) {
           if (valKey.startsWith(DICT.ATTR_BIND_PX)) {
             fnCtx.add(valKey, fnCtx.getAttribute(valKey.replace(DICT.ATTR_BIND_PX, '')));
+          } else if (Object.hasOwn(fnCtx, valKey) && fnCtx[valKey] !== undefined) {
+            let ownVal = fnCtx[valKey];
+            fnCtx.add(valKey, typeof ownVal === 'function' ? ownVal.bind(fnCtx) : ownVal);
+          } else if (typeof fnCtx[valKey] === 'function') {
+            fnCtx.add(valKey, fnCtx[valKey].bind(fnCtx));
           } else {
             fnCtx.add(valKey, null);
             // Dev-only: warn about bindings that aren't in init$ (likely typos)
-            if (fnCtx.Symbiote?.devMode && !prop.startsWith('on')) {
+            if (fnCtx.Symbiote?.devMode) {
               let known = Object.keys(fnCtx.init$).filter((k) => !k.startsWith('+'));
               console.warn(
                 `[Symbiote dev] <${fnCtx.localName}>: binding key "${valKey}" not found in init$ (auto-initialized to null).\n`
@@ -72,10 +77,6 @@ function domBindProcessor(fr, fnCtx) {
             }
           }
         }
-        // In case of event handler is null, bind to fallback method (if defined):
-        if (prop.startsWith('on') && fnCtx.localCtx.read(valKey) === null && typeof fnCtx[valKey] === 'function') {
-          fnCtx.add(valKey, fnCtx[valKey].bind(fnCtx), true);
-        }
         fnCtx.sub(valKey, (val) => {
           if (castType === 'double') {
             val = !!val;
@@ -159,6 +160,11 @@ const txtNodesProcessor = function (fr, fnCtx) {
         if (prop.startsWith(DICT.ATTR_BIND_PX)) {
           fnCtx.add(prop, fnCtx.getAttribute(prop.replace(DICT.ATTR_BIND_PX, '')));
           fnCtx.initAttributeObserver();
+        } else if (Object.hasOwn(fnCtx, prop) && fnCtx[prop] !== undefined) {
+          let ownVal = fnCtx[prop];
+          fnCtx.add(prop, typeof ownVal === 'function' ? ownVal.bind(fnCtx) : ownVal);
+        } else if (typeof fnCtx[prop] === 'function') {
+          fnCtx.add(prop, fnCtx[prop].bind(fnCtx));
         } else {
           fnCtx.add(prop, null);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.0.5",
+  "version": "3.1.2",
   "description": "Symbiote.js - zero-dependency close-to-platform frontend library to build super-powered web components",
   "author": "team@rnd-pro.com",
   "license": "MIT",

package/types/core/itemizeProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"itemizeProcessor.d.ts","sourceRoot":"","sources":["../../core/itemizeProcessor.js"],"names":[],"mappings":"AASA,iCAJgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC,QAoFX"}
+{"version":3,"file":"itemizeProcessor.d.ts","sourceRoot":"","sources":["../../core/itemizeProcessor.js"],"names":[],"mappings":"AASA,iCAJgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC,QAyFX"}

package/types/core/tpl-processors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tpl-processors.d.ts","sourceRoot":"","sources":["../../core/tpl-processors.js"],"names":[],"mappings":"0BAgIgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC"}
+{"version":3,"file":"tpl-processors.d.ts","sourceRoot":"","sources":["../../core/tpl-processors.js"],"names":[],"mappings":"0BAiIgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC"}