@symbiotejs/symbiote 3.3.8 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 3.4.0
+
+### Added
+
+- **DevMode warning for `{{prop}}` in SSR/ISO mode.** Text-node bindings produce no `bind=` attribute in SSR output, so they render correctly on the server but cannot be hydrated on the client. When `devMode = true` and the component has `ssrMode` or `isoMode` enabled, a `console.warn` now suggests using `${{textContent: 'prop'}}` for hydratable text.
+
+## 3.3.9
+
+### Improved
+
+- **DRY itemize processors.** Extracted shared setup logic (element discovery, SSR hydration, class creation, template derivation, attribute cleanup) into `itemizeSetup.js`. Both `itemizeProcessor.js` and `itemizeProcessor-keyed.js` now use the same setup, eliminating code duplication.
+
+- **Keyed processor SSR support.** `itemizeProcessor-keyed.js` now inherits all SSR hydration fixes: `clientSSR` detection, SSR tag adoption, `isoMode` on items, static template derivation, conditional child clearing, and `initPropFallback`.
+
+### Fixed
+
+- **Keyed processor: live HTMLCollection bug.** Fixed `animateOut` failing when removing multiple items by key — the live `HTMLCollection` shifted indices during removal. Elements are now snapshotted before removal.
+
+## 3.3.8
+
+### Fixed
+
+- **SSR hydration: Itemize template derivation.** Dynamically added itemize items now use the original template (parsed from `fnCtx.constructor.template`) instead of SSR-expanded `innerHTML`. This preserves nested custom elements (e.g. icons) in new items added after hydration.
+
 ## 3.3.7
 
 ### Fixed

package/README.md

@@ -11,7 +11,7 @@
 
 A lightweight, standards-first UI library built on Web Components. No virtual DOM, no compiler, no build step required — works directly in the browser. A bundler is recommended for production performance, but entirely optional. **~6kb** gzipped.
 
-Symbiote.js gives you the convenience of a modern framework while staying close to the native platform — HTML, CSS, and DOM APIs. Components are real custom elements that work everywhere: in any framework, in plain HTML, or in a micro-frontend architecture.
+Symbiote.js gives you the convenience of a modern framework while staying close to the native platform — HTML, CSS, and DOM APIs. Components are real custom elements that work everywhere: in any framework, in plain HTML, or in a micro-frontend architecture. And with **isomorphic mode**, the same component code works on the server and the client — server-rendered pages hydrate automatically, no diffing, no mismatch errors.
 
 ## What's new in 3.x
 
@@ -61,57 +61,57 @@ npm i @symbiotejs/symbiote
 import Symbiote, { html, css } from '@symbiotejs/symbiote';
 ```
 
-## SSR — simpler than you'd expect
+## Isomorphic Web Components
 
-Symbiote's SSR doesn't need a virtual DOM, a reconciler, or framework-specific server packages. It's one class:
+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:
 
 ```js
-import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
-
-await SSR.init();              // patches globals with linkedom
-await import('./my-app.js');   // your components register normally
+class MyComponent extends Symbiote {
+  isoMode = true;
+  count = 0;
+  increment() {
+    this.$.count++;
+  }
+}
 
-let html = await SSR.processHtml('<my-app>slot content</my-app>');
-SSR.destroy();                 // cleanup
+MyComponent.template = html`
+  <h2>{{count}}</h2>
+  <button ${{onclick: 'increment'}}>Click me!</button>
+`;
+MyComponent.reg('my-component');
 ```
 
-On the client, components with `ssrMode = true` skip template injection and attach bindings to the existing DOM. State mutations work immediately — no hydration step, no reconciliation, no diffing. For isomorphic components that may or may not be server-rendered, use `isoMode = true` — it detects children automatically.
+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.
 
-### Streaming
+### SSR — one class, zero config
 
-For large pages, stream HTML chunks instead of building a string:
+Server rendering doesn't need a virtual DOM, a reconciler, or framework-specific packages:
 
 ```js
 import { SSR } from '@symbiotejs/symbiote/node/SSR.js';
 
-await SSR.init();
-await import('./my-app.js');
+await SSR.init();              // patches globals with linkedom
+await import('./my-app.js');   // components register normally
 
-http.createServer(async (req, res) => {
-  res.writeHead(200, { 'Content-Type': 'text/html' });
-  res.write('<!DOCTYPE html><html><body>');
-  for await (let chunk of SSR.renderToStream('my-app')) {
-    res.write(chunk);
-  }
-  res.end('</body></html>');
-}).listen(3000);
+let html = await SSR.processHtml('<my-app></my-app>');
+SSR.destroy();
 ```
 
+For large pages, stream HTML chunks with `SSR.renderToStream()` for faster TTFB. See [SSR docs](./docs/ssr.md) and [server setup recipes](./docs/ssr-server.md).
+
 ### How it compares
 
 | | **Symbiote.js** | **Next.js (React)** | **Lit** (`@lit-labs/ssr`) |
-|--|----------------|---------------------|--------------------------|
-| **Architecture** | Binding-based. Client attaches to existing DOM | Virtual DOM. Client re-renders and diffs against server HTML | Template-based with comment markers |
-| **Hydration** | `ssrMode = true` — one flag, no diffing | `hydrateRoot()` — must produce identical output or errors | Requires `ssr-client` + hydrate support module loaded before Lit |
-| **Packages** | 1 module (`node/SSR.js`) + `linkedom` peer dep | Next.js framework (full buy-in) | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
+|--|----------------|---------------------|----|
+| **Isomorphic code** | Same code, `isoMode` auto-detects | Server Components vs Client Components split | Same code, but load-order constraints |
+| **Hydration** | Binding-based — attaches to existing DOM, no diffing | `hydrateRoot()` — must produce identical output or errors | Requires `ssr-client` + hydrate support module |
+| **Packages** | 1 module + `linkedom` peer dep | Full framework buy-in | 3 packages: `ssr`, `ssr-client`, `ssr-dom-shim` |
 | **Streaming** | `renderToStream()` async generator | `renderToPipeableStream()` | Iterable `RenderResult` |
-| **Mismatch handling** | Not needed — bindings attach to whatever DOM exists | Hard errors or visual glitches if server/client output differs | N/A |
-| **Component code** | Same code, no changes | Server Components vs Client Components split | Same code, but load-order constraints |
+| **Mismatch handling** | Not needed — bindings attach to whatever DOM exists | Hard errors if server/client output differs | N/A |
 | **Template output** | Clean HTML with `bind=` attributes | HTML with framework markers | HTML with `<!--lit-part-->` comment markers |
-| **Bundle impact** | Zero — SSR module is server-only | React runtime required on client | Zero — SSR packages are server-only |
 | **Lock-in** | None — standard Web Components | Full framework commitment | Lit-specific, but Web Components |
 
-**Key insight:** Symbiote's SSR is simpler because it doesn't try to reconcile server and client output. The server produces HTML with binding attributes preserved. The client reads those attributes and adds reactivity. No comparison, no diffing, no mismatch errors.
+**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.
 
 ## Core concepts
 

package/core/itemizeProcessor-keyed.js

@@ -1,6 +1,5 @@
-import { DICT } from './dictionary.js';
 import { animateOut } from './animateOut.js';
-import { ownElements } from './ownElements.js';
+import { setupItemize } from './itemizeSetup.js';
 
 /**
  * Optimized itemize template processor.
@@ -30,31 +29,7 @@ import { ownElements } from './ownElements.js';
  * @param {T} fnCtx
  */
 export function itemizeProcessor(fr, fnCtx) {
-  ownElements(fr, `[${DICT.LIST_ATTR}]`).filter((el) => {
-    return !el.matches(`[${DICT.LIST_ATTR}] [${DICT.LIST_ATTR}]`);
-  }).forEach((el) => {
-    let itemTag = el.getAttribute(DICT.LIST_ITEM_TAG_ATTR);
-    let itemClass;
-    if (itemTag) {
-      itemClass = window.customElements.get(itemTag);
-    }
-    if (!itemClass) {
-      itemClass = class extends fnCtx.Symbiote {
-        constructor() {
-          super();
-          if (!itemTag) {
-            this.style.display = 'contents';
-          }
-        }
-      };
-      itemClass.template = el.querySelector('template')?.innerHTML || el.innerHTML;
-      itemClass.reg(itemTag);
-    }
-    while (el.firstChild) {
-      el.firstChild.remove();
-    }
-    let repeatDataKey = el.getAttribute(DICT.LIST_ATTR);
-
+  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR }) => {
     /** @type {*[]} */
     let prevData = [];
 
@@ -180,8 +155,9 @@ export function itemizeProcessor(fr, fnCtx) {
             }
           }
 
-          for (let key of toRemove) {
-            animateOut(children[prevKeyToIdx.get(key)]);
+          let removeEls = [...toRemove].map((key) => children[prevKeyToIdx.get(key)]);
+          for (let el of removeEls) {
+            animateOut(el);
           }
 
           for (let i = 0; i < newChildren.length; i++) {
@@ -226,10 +202,6 @@ export function itemizeProcessor(fr, fnCtx) {
       }
 
       prevData = items;
-    });
-    if (!globalThis.__SYMBIOTE_SSR) {
-      el.removeAttribute(DICT.LIST_ATTR);
-      el.removeAttribute(DICT.LIST_ITEM_TAG_ATTR);
-    }
+    }, !clientSSR);
   });
 }

package/core/itemizeProcessor.js

@@ -1,7 +1,5 @@
-import { DICT } from './dictionary.js';
 import { animateOut } from './animateOut.js';
-import { ownElements } from './ownElements.js';
-import { initPropFallback } from './initPropFallback.js';
+import { setupItemize } from './itemizeSetup.js';
 
 /**
  * @template {import('./Symbiote.js').Symbiote} T
@@ -9,118 +7,58 @@ import { initPropFallback } from './initPropFallback.js';
  * @param {T} fnCtx
  */
 export function itemizeProcessor(fr, fnCtx) {
-  let clientSSR = fnCtx.ssrMode && !globalThis.__SYMBIOTE_SSR;
-
-  ownElements(fr, `[${DICT.LIST_ATTR}]`).filter((el) => {
-      return !el.matches(`[${DICT.LIST_ATTR}] [${DICT.LIST_ATTR}]`);
-    }).forEach((el) => {
-      let itemTag = el.getAttribute(DICT.LIST_ITEM_TAG_ATTR);
-      let repeatDataKey = el.getAttribute(DICT.LIST_ATTR);
-      let itemClass;
-      if (itemTag) {
-        itemClass = window.customElements.get(itemTag);
-      }
-      if (!itemClass) {
-        // During hydration, adopt existing SSR item tag and derive template
-        if (clientSSR && el.children.length > 0) {
-          let ssrTag = el.children[0].localName;
-          itemClass = window.customElements.get(ssrTag);
-          if (!itemClass) {
-            itemClass = class extends fnCtx.Symbiote {
-              constructor() {
-                super();
-                this.isoMode = true;
-                if (!itemTag) {
-                  this.style.display = 'contents';
-                }
-              }
-            };
-            let tpl = document.createElement('template');
-            // @ts-expect-error
-            tpl.innerHTML = fnCtx.constructor.template;
-            let staticEl = tpl.content.querySelector(
-              `[${DICT.LIST_ATTR}="${repeatDataKey}"]`
-            );
-            itemClass.template = staticEl?.querySelector('template')?.innerHTML
-              || el.children[0].innerHTML;
-            itemClass.reg(ssrTag);
-          }
-        } else {
-          itemClass = class extends fnCtx.Symbiote {
-            constructor() {
-              super();
-              if (!itemTag) {
-                this.style.display = 'contents';
-              }
-            }
-          };
-          itemClass.template = el.querySelector('template')?.innerHTML || el.innerHTML;
-          itemClass.reg(itemTag);
-        }
-      }
-      if (!clientSSR) {
+  setupItemize(fr, fnCtx, ({ el, itemClass, repeatDataKey, clientSSR }) => {
+    fnCtx.sub(repeatDataKey, (data) => {
+      if (!data) {
         while (el.firstChild) {
           el.firstChild.remove();
         }
+        return;
       }
-      if (!fnCtx.has(repeatDataKey) && fnCtx.allowTemplateInits) {
-        initPropFallback(fnCtx, repeatDataKey);
-      }
-      fnCtx.sub(repeatDataKey, (data) => {
-        if (!data) {
-          while (el.firstChild) {
-            el.firstChild.remove();
-          }
-          return;
-        }
-        /** @type {*[]} */
-        let currentList = [...el.children];
-        let fragment;
-        let fillItems = (/** @type {*[]} */ items) => {
-          items.forEach((item, idx) => {
-            if (currentList[idx]) {
-              if (currentList[idx].set$) {
-                currentList[idx].set$(item);
-              } else {
-                for (let k in item) {
-                  currentList[idx][k] = item[k];
-                }
-              }
+      /** @type {*[]} */
+      let currentList = [...el.children];
+      let fragment;
+      let fillItems = (/** @type {*[]} */ items) => {
+        items.forEach((item, idx) => {
+          if (currentList[idx]) {
+            if (currentList[idx].set$) {
+              currentList[idx].set$(item);
             } else {
-              if (!fragment) {
-                fragment = document.createDocumentFragment();
+              for (let k in item) {
+                currentList[idx][k] = item[k];
               }
-              let repeatItem = new itemClass();
-              Object.assign((repeatItem?.init$ || repeatItem), item);
-              fragment.appendChild(repeatItem);
             }
-          });
-          fragment && el.appendChild(fragment);
-          let oversize = currentList.slice(items.length, currentList.length);
-          for (let exItm of oversize) {
-            animateOut(exItm);
-          }
-        };
-        if (data.constructor === Array) {
-          fillItems(data);
-        } else if (data.constructor === Object) {
-          let items = [];
-          for (let itemKey in data) {
-            let init = data[itemKey];
-            Object.defineProperty(init, '_KEY_', {
-              value: itemKey,
-              enumerable: true,
-            });
-            items.push(init);
+          } else {
+            if (!fragment) {
+              fragment = document.createDocumentFragment();
+            }
+            let repeatItem = new itemClass();
+            Object.assign((repeatItem?.init$ || repeatItem), item);
+            fragment.appendChild(repeatItem);
           }
-          fillItems(items);
-        } else {
-          console.warn(`[Symbiote] <${fnCtx.localName}>: itemize data must be Array or Object, got ${typeof data}:`, data);
+        });
+        fragment && el.appendChild(fragment);
+        let oversize = currentList.slice(items.length, currentList.length);
+        for (let exItm of oversize) {
+          animateOut(exItm);
+        }
+      };
+      if (data.constructor === Array) {
+        fillItems(data);
+      } else if (data.constructor === Object) {
+        let items = [];
+        for (let itemKey in data) {
+          let init = data[itemKey];
+          Object.defineProperty(init, '_KEY_', {
+            value: itemKey,
+            enumerable: true,
+          });
+          items.push(init);
         }
-      }, !clientSSR);
-      if (!globalThis.__SYMBIOTE_SSR) {
-        el.removeAttribute(DICT.LIST_ATTR);
-        el.removeAttribute(DICT.LIST_ITEM_TAG_ATTR);
+        fillItems(items);
+      } else {
+        console.warn(`[Symbiote] <${fnCtx.localName}>: itemize data must be Array or Object, got ${typeof data}:`, data);
       }
-    });
+    }, !clientSSR);
+  });
 }

package/core/itemizeSetup.js

@@ -0,0 +1,88 @@
+import { DICT } from './dictionary.js';
+import { ownElements } from './ownElements.js';
+import { initPropFallback } from './initPropFallback.js';
+
+/**
+ * @typedef {Object} ItemizeDescriptor
+ * @property {Element} el
+ * @property {*} itemClass
+ * @property {string} repeatDataKey
+ * @property {boolean} clientSSR
+ */
+
+/**
+ * Shared setup for itemize processors.
+ * Handles element discovery, class creation, SSR hydration, template derivation,
+ * child clearing, initPropFallback, and attribute cleanup.
+ *
+ * @template {import('./Symbiote.js').Symbiote} T
+ * @param {DocumentFragment} fr
+ * @param {T} fnCtx
+ * @param {(desc: ItemizeDescriptor) => void} handler
+ */
+export function setupItemize(fr, fnCtx, handler) {
+  let clientSSR = fnCtx.ssrMode && !globalThis.__SYMBIOTE_SSR;
+
+  ownElements(fr, `[${DICT.LIST_ATTR}]`).filter((el) => {
+    return !el.matches(`[${DICT.LIST_ATTR}] [${DICT.LIST_ATTR}]`);
+  }).forEach((el) => {
+    let itemTag = el.getAttribute(DICT.LIST_ITEM_TAG_ATTR);
+    let repeatDataKey = el.getAttribute(DICT.LIST_ATTR);
+    let itemClass;
+    if (itemTag) {
+      itemClass = window.customElements.get(itemTag);
+    }
+    if (!itemClass) {
+      if (clientSSR && el.children.length > 0) {
+        let ssrTag = el.children[0].localName;
+        itemClass = window.customElements.get(ssrTag);
+        if (!itemClass) {
+          itemClass = class extends fnCtx.Symbiote {
+            constructor() {
+              super();
+              this.isoMode = true;
+              if (!itemTag) {
+                this.style.display = 'contents';
+              }
+            }
+          };
+          let tpl = document.createElement('template');
+          // @ts-expect-error
+          tpl.innerHTML = fnCtx.constructor.template;
+          let staticEl = tpl.content.querySelector(
+            `[${DICT.LIST_ATTR}="${repeatDataKey}"]`
+          );
+          itemClass.template = staticEl?.querySelector('template')?.innerHTML
+            || el.children[0].innerHTML;
+          itemClass.reg(ssrTag);
+        }
+      } else {
+        itemClass = class extends fnCtx.Symbiote {
+          constructor() {
+            super();
+            if (!itemTag) {
+              this.style.display = 'contents';
+            }
+          }
+        };
+        itemClass.template = el.querySelector('template')?.innerHTML || el.innerHTML;
+        itemClass.reg(itemTag);
+      }
+    }
+    if (!clientSSR) {
+      while (el.firstChild) {
+        el.firstChild.remove();
+      }
+    }
+    if (!fnCtx.has(repeatDataKey) && fnCtx.allowTemplateInits) {
+      initPropFallback(fnCtx, repeatDataKey);
+    }
+
+    handler({ el, itemClass, repeatDataKey, clientSSR });
+
+    if (!globalThis.__SYMBIOTE_SSR) {
+      el.removeAttribute(DICT.LIST_ATTR);
+      el.removeAttribute(DICT.LIST_ITEM_TAG_ATTR);
+    }
+  });
+}

package/core/tpl-processors.js

@@ -155,6 +155,13 @@ const txtNodesProcessor = function (fr, fnCtx) {
       if (!fnCtx.has(prop) && fnCtx.allowTemplateInits) {
         initPropFallback(fnCtx, prop);
       }
+      if (fnCtx.Symbiote?.devMode && (fnCtx.ssrMode || fnCtx.isoMode)) {
+        console.warn(
+          `[Symbiote dev] <${fnCtx.localName}>: text-node binding "{{${prop}}}" has no hydration attribute. `
+          + 'In ssrMode/isoMode it will be rendered by the server but won\'t update on the client. '
+          + 'Use property binding (${{textContent: \'' + prop + '\'}}) for hydratable text.'
+        );
+      }
       fnCtx.sub(prop, (val) => {
         tNode.textContent = val;
       });

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.3.8",
+  "version": "3.4.0",
   "description": "Symbiote.js - zero-dependency close-to-platform frontend library to build super-powered web components",
   "author": "team@rnd-pro.com",
   "license": "MIT",
@@ -87,6 +87,10 @@
       "types": "./types/core/itemizeProcessor.d.ts",
       "default": "./core/itemizeProcessor.js"
     },
+    "./core/itemizeSetup.js": {
+      "types": "./types/core/itemizeSetup.d.ts",
+      "default": "./core/itemizeSetup.js"
+    },
     "./core/ownElements.js": {
       "types": "./types/core/ownElements.d.ts",
       "default": "./core/ownElements.js"

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

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

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

package/types/core/itemizeSetup.d.ts

@@ -0,0 +1,8 @@
+export function setupItemize<T extends import("./Symbiote.js").Symbiote<any>>(fr: DocumentFragment, fnCtx: T, handler: (desc: ItemizeDescriptor) => void): void;
+export type ItemizeDescriptor = {
+    el: Element;
+    itemClass: any;
+    repeatDataKey: string;
+    clientSSR: boolean;
+};
+//# sourceMappingURL=itemizeSetup.d.ts.map

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

@@ -0,0 +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"}