@symbiotejs/symbiote 3.5.8 → 3.6.0

package/AI_REFERENCE.md

@@ -441,7 +441,7 @@ class MyList extends Symbiote {
 }
 
 MyList.template = html`
-  <ul ${{itemize: 'items'}}>
+  <ul itemize="items">
     <template>
       <li>
         <span>{{name}}</span> - <span>{{role}}</span>
@@ -452,17 +452,41 @@ MyList.template = html`
 `;
 ```
 
-> **CRITICAL**: Inside itemize templates, items are full Symbiote components with their own state scope.
-> - `{{name}}` — item's own property
-> - `${{onclick: 'handler'}}` — binds to the item component's own method/property
-> - `${{onclick: '^handler'}}` — use `^` prefix to reach the **parent** component's property (must be in parent's `init$`)
-> - Failure to use `^` for parent handlers will result in broken event bindings
+> **CRITICAL**: Inside itemize, each item is a Symbiote component with its own state scope.
+> There are **two patterns** — they determine how event handlers are bound:
+>
+> **Pattern 1: Inline `<template>` (dumb items)** — items have no class definition, only data properties from the array.
+> Any event handler or data must come from an **external context** — not from the item itself.
+> All context prefixes work: `^` (parent pop-up), `APP/` (named), `*` (shared). The most common is `^`:
+> ```html
+> <ul itemize="items">
+>   <template>
+>     <li>{{name}} <button ${{onclick: '^onItemClick'}}>Click</button></li>
+>   </template>
+> </ul>
+> ```
+> Without a context prefix, the binding looks for the handler on the item itself — which doesn't have it, so it breaks.
+>
+> **Pattern 2: Custom `item-tag` (smart items)** — items are full components with their own class, templates, and methods.
+> Handlers defined on the item component itself do **NOT** need `^`:
+> ```html
+> <div itemize="items" item-tag="my-item"></div>
+> ```
+> ```js
+> class MyItem extends Symbiote {
+>   onItemClick() { console.log(this.$.name); }
+> }
+> MyItem.template = html`<li>{{name}} <button ${{onclick: 'onItemClick'}}>Click</button></li>`;
+> MyItem.reg('my-item');
+> ```
+> Here `onItemClick` is the item's own method — no `^` needed.
+> You can still use `^` to reach the parent list component if needed.
 
 ### Custom item component
 ```html
-<div ${{itemize: 'items', 'item-tag': 'my-item'}}></div>
+<div itemize="items" item-tag="my-item"></div>
 ```
-Then define `my-item` as a separate Symbiote component.
+Then define `my-item` as a separate Symbiote component with its own template, methods, and state.
 
 ### Data formats
 - **Array**: `[{prop: val}, ...]` — items rendered in order
@@ -799,7 +823,7 @@ import '@symbiotejs/symbiote/core/devMessages.js';
 
 1. **DON'T** use `this` in template strings — templates are decoupled from component context
 2. **DON'T** nest property keys with dots in state: `'obj.prop'` won't work as a state key
-3. **DON'T** forget `^` prefix when referencing **parent** component properties from itemize items
+3. **DON'T** forget `^` prefix when referencing **parent** handlers from inline `<template>` itemize items (dumb items without their own class). Custom `item-tag` components with own methods bind directly without `^`
 4. **DON'T** use `@` prefix directly in HTML — it's only for binding syntax (`${{'@attr': 'prop'}}`)
 5. **DON'T** treat `init$` as a regular object — it's processed at connection time
 6. **DON'T** define `template` inside the class body (`static template = html\`...\`` won't work) — it's a static property **setter**, assign it outside: `MyComponent.template = html\`...\``. Same applies to `rootStyles` and `shadowStyles`.

package/README.md

@@ -23,6 +23,7 @@ Symbiote.js gives you the convenience of a modern framework while staying close
 - **Dev mode** - `Symbiote.devMode` enables verbose warnings; import `devMessages.js` for full human-readable messages.
 - **DSD hydration** - `ssrMode` supports both light DOM and Declarative Shadow DOM.
 - **Class property fallback** - binding keys not in `init$` fall back to own class properties/methods.
+- **Lazy mode** - `lazyMode` flag defers component initialization and rendering based on viewport visibility. Can also be enabled via the `lazy` attribute on `itemize` containers to efficiently handle massive data sets.
 - And [more](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md).
 
 ## Quick start
@@ -184,6 +185,8 @@ TaskList.template = html`
 
 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$`.
 
+> **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.
+
 ### Pop-up binding (`^`)
 
 The `^` prefix works in any nested component template - it walks up the DOM tree to find the nearest ancestor that has the property registered in its data context (`init$` or `add$()`):

package/core/Symbiote.js

@@ -19,6 +19,9 @@ const trustedHTML = globalThis.trustedTypes ? trustedTypes.createPolicy('symbiot
 
 /** @template S */
 export class Symbiote extends HTMLElement {
+  /** @type {IntersectionObserver} */
+  static lazyObserver;
+
   /** @type {Boolean} */
   #initialized;
   /** @type {String} */
@@ -187,6 +190,8 @@ export class Symbiote extends HTMLElement {
     this.isVirtual = false;
     /** @type {Boolean} */
     this.allowTemplateInits = true;
+    /** @type {Boolean} */
+    this.lazyMode = false;
   }
 
   /** @returns {String} */
@@ -516,7 +521,52 @@ export class Symbiote extends HTMLElement {
   }
 
   connectedCallback() {
-    this.#initComponent();
+    if (this.lazyMode) {
+      if (!Symbiote.lazyObserver) {
+        Symbiote.lazyObserver = new IntersectionObserver((entries) => {
+          entries.forEach((ent) => {
+            /** @type {any} */
+            let tgt = ent.target;
+            if (ent.isIntersecting) {
+              tgt.style.minHeight = '';
+              tgt.style.minWidth = '';
+              tgt.#initComponent();
+            } else {
+              tgt.#lazyDestroy();
+            }
+          });
+        });
+      }
+      Symbiote.lazyObserver.observe(this);
+    } else {
+      this.#initComponent();
+    }
+  }
+
+  #lazyDestroy() {
+    if (!this.connectedOnce) {
+      return;
+    }
+    let rect = this.getBoundingClientRect();
+    if (rect.height) {
+      this.style.minHeight = rect.height + 'px';
+      this.style.minWidth = rect.width + 'px';
+    }
+    if (this.shadowRoot) {
+      this.shadowRoot.innerHTML = '';
+    } else {
+      this.innerHTML = '';
+    }
+    for (let sub of this.allSubs) {
+      sub.remove();
+      this.allSubs.delete(sub);
+    }
+    this.#localCtx = null;
+    this.templateProcessors.clear();
+    
+    this.connectedOnce = false;
+    this.#dataCtxInitialized = false;
+    this.#initialized = false;
   }
 
   destroyCallback() {}
@@ -532,6 +582,9 @@ export class Symbiote extends HTMLElement {
   destructionDelay = 100;
   disconnectedCallback() {
     if (globalThis.__SYMBIOTE_SSR) return;
+    if (this.lazyMode && Symbiote.lazyObserver) {
+      Symbiote.lazyObserver.unobserve(this);
+    }
     // if element wasn't connected, there is no need to disconnect it
     if (!this.connectedOnce) {
       return;

package/core/itemizeProcessor-keyed.js

@@ -30,7 +30,7 @@ import { setupItemize } from './itemizeSetup.js';
  * @param {T} fnCtx
  */
 export function itemizeProcessor(fr, fnCtx) {
-  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR }) => {
+  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR, isLazy }) => {
     /** @type {*[]} */
     let prevData = [];
 
@@ -88,6 +88,9 @@ export function itemizeProcessor(fr, fnCtx) {
           let fragment = document.createDocumentFragment();
           for (let i = prevLen; i < newLen; i++) {
             let repeatItem = new itemClass();
+            if (isLazy) {
+              repeatItem.lazyMode = true;
+            }
             Object.assign((repeatItem?.init$ || repeatItem), items[i]);
             fragment.appendChild(repeatItem);
           }
@@ -151,6 +154,9 @@ export function itemizeProcessor(fr, fnCtx) {
               newChildren.push(existing);
             } else {
               let repeatItem = new itemClass();
+              if (isLazy) {
+                repeatItem.lazyMode = true;
+              }
               Object.assign((repeatItem?.init$ || repeatItem), item);
               newChildren.push(repeatItem);
             }
@@ -193,6 +199,9 @@ export function itemizeProcessor(fr, fnCtx) {
             fragment = document.createDocumentFragment();
           }
           let repeatItem = new itemClass();
+          if (isLazy) {
+            repeatItem.lazyMode = true;
+          }
           Object.assign((repeatItem?.init$ || repeatItem), items[i]);
           fragment.appendChild(repeatItem);
         }

package/core/itemizeProcessor.js

@@ -8,7 +8,7 @@ import { setupItemize } from './itemizeSetup.js';
  * @param {T} fnCtx
  */
 export function itemizeProcessor(fr, fnCtx) {
-  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR }) => {
+  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR, isLazy }) => {
     fnCtx.sub(repeatDataKey, (data) => {
       if (!data) {
         while (el.firstChild) {
@@ -34,6 +34,9 @@ export function itemizeProcessor(fr, fnCtx) {
               fragment = document.createDocumentFragment();
             }
             let repeatItem = new itemClass();
+            if (isLazy) {
+              repeatItem.lazyMode = true;
+            }
             Object.assign((repeatItem?.init$ || repeatItem), item);
             fragment.appendChild(repeatItem);
           }

package/core/itemizeSetup.js

@@ -8,6 +8,7 @@ import { initPropFallback } from './initPropFallback.js';
  * @property {*} itemClass
  * @property {string} repeatDataKey
  * @property {boolean} clientSSR
+ * @property {boolean} isLazy
  */
 
 /**
@@ -78,7 +79,8 @@ export function setupItemize(fr, fnCtx, handler) {
       initPropFallback(fnCtx, repeatDataKey);
     }
 
-    handler({ el, itemClass, repeatDataKey, clientSSR });
+    let isLazy = el.hasAttribute('lazy');
+    handler({ el, itemClass, repeatDataKey, clientSSR, isLazy });
 
     if (!globalThis.__SYMBIOTE_SSR) {
       el.removeAttribute(DICT.LIST_ATTR);

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.5.8",
+  "version": "3.6.0",
   "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/Symbiote.d.ts

@@ -1,6 +1,7 @@
 export { html } from "./html.js";
 export { css } from "./css.js";
 export class Symbiote<S> extends HTMLElement {
+    static lazyObserver: IntersectionObserver;
     static __tpl: HTMLTemplateElement;
     static set devMode(val: boolean);
     static get devMode(): boolean;
@@ -38,6 +39,7 @@ export class Symbiote<S> extends HTMLElement {
     allowCustomTemplate: boolean;
     isVirtual: boolean;
     allowTemplateInits: boolean;
+    lazyMode: boolean;
     get cssCtxName(): string;
     get ctxName(): string;
     get localCtx(): PubSub<any>;

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

@@ -1 +1 @@
-{"version":3,"file":"Symbiote.d.ts","sourceRoot":"","sources":["../../core/Symbiote.js"],"names":[],"mappings":";;AAoBA,sBADc,CAAC;IAuBb,cADW,mBAAmB,CACjB;IAEb,iCAEC;IAED,8BAEC;IAkBD,wBAAgB;IA8JhB,+BAJwB,CAAC,SAAZ,aAAU,uBAEZ,CAAC;;;MA0CX;IAuQD,qCAA+B;IAqC/B,iDAFa,OAAO,QAAQ,CAkB3B;IAED,wBAKC;IAGD;;aAYC;IAmHD,6BADY,SAAS,aAAa,QAOjC;IAGD,+BADY,SAAS,aAAa,QAOjC;IAGD,8BADY,SAAS,aAAa,EAIjC;IAGD,gCADY,SAAS,aAAa,EAIjC;IA1kBD,cA6BC;IAzID,gCAEC;IAED,qBAAiB;IACjB,uBAAmB;IAiBnB,kBAHW,SAAS,gBAAgB,0BAuFnC;IAxDG,aAAiD;IA6DnD,OADW,CAAC,CACoB;IAEhC;;MAAmC;IAEnC,oBADW,GAAG,CAAC,CAAC,EAAE,EAAE,gBAAgB,gBAAW,EAAE,KAAK,eAAU,KAAK,IAAI,CAAC,CACvC;IAEnC;;MAA8B;IAC9B,kBAAwB;IAExB,qBAAwB;IAExB,sBAAyB;IAEzB,wBAA0B;IAE1B,0BAA6B;IAI7B,iBAAoB;IAEpB,6BAAgC;IAEhC,mBAAsB;IAEtB,4BAA8B;IAIhC,yBAEC;IAGD,sBASC;IAGD,4BAKC;IAGD,6BAEC;IAuDD,IALuB,CAAC,SAAX,MAAO,CAAE,QACX,CAAC,WACD,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,wBAuC/B;IAGD,2BAIC;IAGD,uBAIC;IAQD,IALuB,CAAC,SAAX,MAAO,CAAE,qBAEX,CAAC,CAAC,CAAC,CAAC,2BAOd;IAMD,UAHW,OAAO,CAAC,CAAC,CAAC,2BAOpB;IAGD,SADc,CAAC,CA6Bd;IAMD,YAHW,OAAO,CAAC,CAAC,CAAC,mCAcpB;IAED,8BAgBC;IAdG,4CASE;IAmFF,0BAAwC;IAwB1C,uBAAyB;IAG3B,0BAEC;IAED,wBAAoB;IAUpB,yBAAuB;IACvB,6BA2BC;IA+CD,oEAeC;IAMD,yDAoBC;IAYD,0BAME;IAMF,0CAFW,GAAG,QAgBb;IAED,yBAGC;IAOD,8EAmBC;;CA+BF;;mBA3uBkB,aAAa;qBAEX,iBAAiB;2BACX,iBAAiB"}
+{"version":3,"file":"Symbiote.d.ts","sourceRoot":"","sources":["../../core/Symbiote.js"],"names":[],"mappings":";;AAoBA,sBADc,CAAC;IAGb,qBADW,oBAAoB,CACX;IAuBpB,cADW,mBAAmB,CACjB;IAEb,iCAEC;IAED,8BAEC;IAkBD,wBAAgB;IAgKhB,+BAJwB,CAAC,SAAZ,aAAU,uBAEZ,CAAC;;;MA0CX;IAoTD,qCAA+B;IAwC/B,iDAFa,OAAO,QAAQ,CAkB3B;IAED,wBAKC;IAGD;;aAYC;IAmHD,6BADY,SAAS,aAAa,QAOjC;IAGD,+BADY,SAAS,aAAa,QAOjC;IAGD,8BADY,SAAS,aAAa,EAIjC;IAGD,gCADY,SAAS,aAAa,EAIjC;IA5nBD,cA+BC;IA3ID,gCAEC;IAED,qBAAiB;IACjB,uBAAmB;IAiBnB,kBAHW,SAAS,gBAAgB,0BAuFnC;IAxDG,aAAiD;IA6DnD,OADW,CAAC,CACoB;IAEhC;;MAAmC;IAEnC,oBADW,GAAG,CAAC,CAAC,EAAE,EAAE,gBAAgB,gBAAW,EAAE,KAAK,eAAU,KAAK,IAAI,CAAC,CACvC;IAEnC;;MAA8B;IAC9B,kBAAwB;IAExB,qBAAwB;IAExB,sBAAyB;IAEzB,wBAA0B;IAE1B,0BAA6B;IAI7B,iBAAoB;IAEpB,6BAAgC;IAEhC,mBAAsB;IAEtB,4BAA8B;IAE9B,kBAAqB;IAIvB,yBAEC;IAGD,sBASC;IAGD,4BAKC;IAGD,6BAEC;IAuDD,IALuB,CAAC,SAAX,MAAO,CAAE,QACX,CAAC,WACD,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,wBAuC/B;IAGD,2BAIC;IAGD,uBAIC;IAQD,IALuB,CAAC,SAAX,MAAO,CAAE,qBAEX,CAAC,CAAC,CAAC,CAAC,2BAOd;IAMD,UAHW,OAAO,CAAC,CAAC,CAAC,2BAOpB;IAGD,SADc,CAAC,CA6Bd;IAMD,YAHW,OAAO,CAAC,CAAC,CAAC,mCAcpB;IAED,8BAgBC;IAdG,4CASE;IAmFF,0BAAwC;IAwB1C,uBAAyB;IAG3B,0BAqBC;IA4BD,wBAAoB;IAUpB,yBAAuB;IACvB,6BA8BC;IA+CD,oEAeC;IAMD,yDAoBC;IAYD,0BAME;IAMF,0CAFW,GAAG,QAgBb;IAED,yBAGC;IAOD,8EAmBC;;CA+BF;;mBAhyBkB,aAAa;qBAEX,iBAAiB;2BACX,iBAAiB"}

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

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

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,QAyDX"}
+{"version":3,"file":"itemizeProcessor.d.ts","sourceRoot":"","sources":["../../core/itemizeProcessor.js"],"names":[],"mappings":"AASA,iCAJgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC,QA4DX"}

package/types/core/itemizeSetup.d.ts

@@ -4,5 +4,6 @@ export type ItemizeDescriptor = {
     itemClass: any;
     repeatDataKey: string;
     clientSSR: boolean;
+    isLazy: boolean;
 };
 //# sourceMappingURL=itemizeSetup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"itemizeSetup.d.ts","sourceRoot":"","sources":["../../core/itemizeSetup.js"],"names":[],"mappings":"AAsBA,6BALgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC,WACD,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,QAmE3C;;QAjFa,OAAO;eACP,GAAC;mBACD,MAAM;eACN,OAAO"}
+{"version":3,"file":"itemizeSetup.d.ts","sourceRoot":"","sources":["../../core/itemizeSetup.js"],"names":[],"mappings":"AAuBA,6BALgD,CAAC,SAApC,qCAAkC,MACpC,gBAAgB,SAChB,CAAC,WACD,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,QAoE3C;;QAnFa,OAAO;eACP,GAAC;mBACD,MAAM;eACN,OAAO;YACP,OAAO"}