@symbiotejs/symbiote 3.2.1 → 3.3.0

package/AI_REFERENCE.md

@@ -153,7 +153,7 @@ Prefixes control which data context a binding resolves to:
 | Prefix | Meaning | Example | Description |
 |--------|---------|---------|-------------|
 | _(none)_ | Local state | `{{count}}` | Current component's local context |
-| `^` | Parent inherited | `{{^parentProp}}` | Walk up DOM ancestry to find nearest component that has this prop |
+| `^` | Parent inherited | `{{^parentProp}}` | Walk up DOM ancestry to find nearest component that has this prop in its data context (`init$` / `add$()`) |
 | `*` | 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 | `{{--my-css-var}}` | Read value from CSS custom property |
@@ -318,6 +318,7 @@ Both components access the same `*files` state — no parent component, no prop
 | `readyToDestroy` | `true` | Allow cleanup on disconnect |
 | `processInnerHtml` | `false` | Process existing inner HTML with template processors |
 | `ssrMode` | `false` | **Client-only.** Hydrate server-rendered HTML: skips template injection, attaches bindings to existing DOM. Supports both light DOM and Declarative Shadow DOM. Ignored when `__SYMBIOTE_SSR` is active (server side) |
+| `isoMode` | `false` | **Client-only.** Isomorphic mode: if component has children at connect time, behaves as `ssrMode = true` (hydrate). If no children, renders template normally. Same component works for both SSR and client-only scenarios |
 | `allowCustomTemplate` | `false` | Allow `use-template="#selector"` attribute |
 | `isVirtual` | `false` | Replace element with its template fragment |
 | `allowTemplateInits` | `true` | Auto-add props found in template but not in init$ |
@@ -454,7 +455,7 @@ 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
+> - `${{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
 
 ### Custom item component
@@ -798,3 +799,4 @@ Symbiote.devMode = true;
 9. **DON'T** use CSS frameworks (Tailwind, etc.) — use native CSS with custom properties
 10. **DON'T** use `require()` — ESM only (import/export)
 11. **DON'T** use `*prop` without `ctx` attribute or `--ctx` CSS variable — shared context won't be created
+12. **DON'T** rely on class property fallbacks for `^`-targeted properties — the `^` walk only checks the parent's data context (`init$` / `add$()`), not own class properties

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 3.3.0
+
+### Added
+
+- **`isoMode` flag for isomorphic rendering.**
+  `isoMode = true` enables automatic detection: if the component has children at connect time (server-rendered content), it hydrates existing DOM like `ssrMode`. If no children exist, it renders the template normally. Same component code works for both SSR and client-only scenarios.
+
 ## 3.2.0
 
 ### Added

package/README.md

@@ -1,5 +1,9 @@
+[![Tests](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml/badge.svg)](https://github.com/symbiotejs/symbiote.js/actions/workflows/tests.yml)
 [![npm version](https://img.shields.io/npm/v/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
-![License](https://img.shields.io/badge/license-MIT-green)
+[![npm downloads](https://img.shields.io/npm/dm/@symbiotejs/symbiote)](https://www.npmjs.com/package/@symbiotejs/symbiote)
+![bundle size](https://img.shields.io/badge/minzip-6.5_kb-blue)
+![types](https://img.shields.io/badge/types-JSDoc+d.ts-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
 
 # Symbiote.js
 
@@ -12,6 +16,7 @@ Symbiote.js gives you the convenience of a modern framework while staying close
 ## What's new in 3.x
 
 - **Server-Side Rendering** — render components to HTML with `SSR.processHtml()` or stream chunks with `SSR.renderToStream()`. Client-side hydration via `ssrMode` attaches bindings to existing DOM without re-rendering.
+- **Isomorphic components** — `isoMode` flag makes components work in both SSR and client-only scenarios automatically. If server-rendered content exists, it hydrates; otherwise it renders the template from scratch. One component, zero conditional logic.
 - **Computed properties** — reactive derived state with microtask batching.
 - **Path-based router** — optional `AppRouter` module with `:param` extraction, route guards, and lazy loading.
 - **Exit animations** — `animateOut(el)` for CSS-driven exit transitions, integrated into itemize API.
@@ -70,7 +75,7 @@ let html = await SSR.processHtml('<my-app>slot content</my-app>');
 SSR.destroy();                 // cleanup
 ```
 
-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.
+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.
 
 ### Streaming
 
@@ -158,15 +163,15 @@ Render lists from data arrays with efficient diffing:
 
 ```js
 class TaskList extends Symbiote {
+  tasks = [
+    { name: 'Buy groceries' },
+    { name: 'Write docs' },
+  ];
   init$ = {
-    tasks: [
-      { name: 'Buy groceries' },
-      { name: 'Write docs' },
-    ],
-  }
-
-  onItemClick() {
-    console.log('clicked!');
+    // Needs to be defined in init$ for bubbling binding to work
+    onItemClick: () => {
+      console.log('clicked!');
+    },
   }
 }
 
@@ -179,11 +184,11 @@ 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.
+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$`.
 
 ### Bubbling binding (`^`)
 
-The `^` prefix works in any nested component template — it walks up the DOM tree to find the nearest ancestor component that owns the property:
+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$()`):
 
 ```html
 <!-- Text binding to parent property: -->
@@ -193,6 +198,8 @@ The `^` prefix works in any nested component template — it walks up the DOM tr
 <button ${{onclick: '^parentHandler'}}>Click</button>
 ```
 
+> **Note:** Class property fallbacks are not checked by the `^` walk — the parent must define the property in `init$`.
+
 ### Named data contexts
 
 Share state across components without prop drilling:
@@ -355,3 +362,7 @@ All modern browsers: Chrome, Firefox, Safari, Edge, Opera.
 - [Changelog](https://github.com/symbiotejs/symbiote.js/blob/main/CHANGELOG.md)
 
 **Questions or proposals? Welcome to [Symbiote Discussions](https://github.com/symbiotejs/symbiote.js/discussions)!** ❤️
+
+---
+
+© [rnd-pro.com](https://rnd-pro.com) — MIT License

package/core/Symbiote.js

@@ -98,6 +98,10 @@ export class Symbiote extends HTMLElement {
         }
       }
     }
+    // Resolve isoMode: hydrate if children exist, render template otherwise
+    if (this.isoMode && !globalThis.__SYMBIOTE_SSR) {
+      this.ssrMode = this.childNodes.length > 0;
+    }
     let clientSSR = this.ssrMode && !globalThis.__SYMBIOTE_SSR;
     if (this.processInnerHtml || clientSSR) {
       for (let fn of this.templateProcessors) {
@@ -169,6 +173,8 @@ export class Symbiote extends HTMLElement {
     /** @type {Boolean} */
     this.ssrMode = false;
     /** @type {Boolean} */
+    this.isoMode = false;
+    /** @type {Boolean} */
     this.allowCustomTemplate = false;
     /** @type {Boolean} */
     this.isVirtual = false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@symbiotejs/symbiote",
-  "version": "3.2.1",
+  "version": "3.3.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

@@ -20,6 +20,7 @@ export class Symbiote<S> extends HTMLElement {
     initCallback(): void;
     renderCallback(): void;
     render(template?: string | DocumentFragment, shadow?: boolean): void;
+    ssrMode: boolean;
     init$: S;
     cssInit$: {
         [x: string]: any;
@@ -33,7 +34,7 @@ export class Symbiote<S> extends HTMLElement {
     renderShadow: boolean;
     readyToDestroy: boolean;
     processInnerHtml: boolean;
-    ssrMode: boolean;
+    isoMode: boolean;
     allowCustomTemplate: boolean;
     isVirtual: boolean;
     allowTemplateInits: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"Symbiote.d.ts","sourceRoot":"","sources":["../../core/Symbiote.js"],"names":[],"mappings":";;AAmBA,sBADc,CAAC;IAuBb,cADW,mBAAmB,CACjB;IAGb,sCAAwB;IAExB,iCAGC;IAED,8BAEC;IAkBD,wBAAgB;IA8IhB,+BAJwB,CAAC,SAAZ,aAAU,uBAEZ,CAAC;;;MAuCX;IA+OD,qCAA+B;IAoC/B,iDAFa,OAAO,QAAQ,CAqB3B;IAED,wBAKC;IAGD;;aAOC;IA6GD,6BADY,SAAS,aAAa,QAOjC;IAGD,+BADY,SAAS,aAAa,QAOjC;IAGD,8BADY,SAAS,aAAa,EAIjC;IAGD,gCADY,SAAS,aAAa,EAIjC;IApiBD,cA2BC;IAzHD,gCAEC;IAED,qBAAiB;IACjB,uBAAmB;IAiBnB,kBAHW,SAAS,gBAAgB,0BAyEnC;IAKC,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;IAE7B,iBAAoB;IAEpB,6BAAgC;IAEhC,mBAAsB;IAEtB,4BAA8B;IAIhC,yBAEC;IAGD,sBASC;IAGD,4BAKC;IAGD,6BAEC;IAoDD,IALuB,CAAC,SAAX,MAAO,CAAE,QACX,CAAC,WACD,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,wBAmB/B;IAGD,2BAGC;IAGD,uBAGC;IAQD,IALuB,CAAC,SAAX,MAAO,CAAE,qBAEX,CAAC,CAAC,CAAC,CAAC,2BAMd;IAMD,UAHW,OAAO,CAAC,CAAC,CAAC,2BAOpB;IAGD,SADc,CAAC,CA2Bd;IAMD,YAHW,OAAO,CAAC,CAAC,CAAC,mCAcpB;IAED,8BAgBC;IAdG,4CASE;IAwFF,0BAAwC;IAoB1C,uBAAyB;IAG3B,0BAEC;IAED,wBAAoB;IAUpB,yBAAuB;IACvB,6BA0BC;IA6CD,oEAeC;IAMD,yDAiBC;IAYD,0BAME;IAMF,0CAFW,GAAG,QAab;IAED,yBAGC;IAOD,8EAmBC;;CA+BF;;mBA1rBkB,aAAa;qBACX,iBAAiB;2BACX,iBAAiB"}
+{"version":3,"file":"Symbiote.d.ts","sourceRoot":"","sources":["../../core/Symbiote.js"],"names":[],"mappings":";;AAmBA,sBADc,CAAC;IAuBb,cADW,mBAAmB,CACjB;IAGb,sCAAwB;IAExB,iCAGC;IAED,8BAEC;IAkBD,wBAAgB;IAoJhB,+BAJwB,CAAC,SAAZ,aAAU,uBAEZ,CAAC;;;MAuCX;IA+OD,qCAA+B;IAoC/B,iDAFa,OAAO,QAAQ,CAqB3B;IAED,wBAKC;IAGD;;aAOC;IA6GD,6BADY,SAAS,aAAa,QAOjC;IAGD,+BADY,SAAS,aAAa,QAOjC;IAGD,8BADY,SAAS,aAAa,EAIjC;IAGD,gCADY,SAAS,aAAa,EAIjC;IAtiBD,cA6BC;IA/HD,gCAEC;IAED,qBAAiB;IACjB,uBAAmB;IAiBnB,kBAHW,SAAS,gBAAgB,0BA6EnC;IAjDG,iBAAyC;IAsD3C,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;IAoDD,IALuB,CAAC,SAAX,MAAO,CAAE,QACX,CAAC,WACD,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,wBAmB/B;IAGD,2BAGC;IAGD,uBAGC;IAQD,IALuB,CAAC,SAAX,MAAO,CAAE,qBAEX,CAAC,CAAC,CAAC,CAAC,2BAMd;IAMD,UAHW,OAAO,CAAC,CAAC,CAAC,2BAOpB;IAGD,SADc,CAAC,CA2Bd;IAMD,YAHW,OAAO,CAAC,CAAC,CAAC,mCAcpB;IAED,8BAgBC;IAdG,4CASE;IAwFF,0BAAwC;IAoB1C,uBAAyB;IAG3B,0BAEC;IAED,wBAAoB;IAUpB,yBAAuB;IACvB,6BA0BC;IA6CD,oEAeC;IAMD,yDAiBC;IAYD,0BAME;IAMF,0CAFW,GAAG,QAab;IAED,yBAGC;IAOD,8EAmBC;;CA+BF;;mBAhsBkB,aAAa;qBACX,iBAAiB;2BACX,iBAAiB"}