@symbiotejs/symbiote 2.0.0-alpha.8 → 2.0.1

package/README.md

@@ -21,9 +21,11 @@ Best for:
 > Symbiote.js is designed to give the level of freedom, you got with Vanilla JS and to give the convenience level, as you got from the modern frameworks at the same time.
 
 ## 🔥 Core benefits
-* Minimal but rich.
+* Symbiote.js - is a total agnostic. It can work with any of modern tools or in the target environment directly.
 * No extra dependencies.
-* Ultralight (~4kb br/gzip for the all BaseComponent features).
+* Ultralight (~6kb br/gzip).
+* Global state-management already included, more powerful and flexible, than ever before.
+* Styling engine already included, based on cutting-edge platform features.
 * Blazing fast.
 * Memory friendly (no immutables).
 * CSP friendly - good for enterprise usage.
@@ -31,34 +33,44 @@ Best for:
 * Easy to learn - nothing completely new for experienced developers, nothing complicated for newbies.
 * Works in all modern browsers. As is.
 * Easy to test.
-* TypeScript friendly - use it in TS or JS projects from the common source code.
+* TypeScript friendly - use it in TS or JS projects from the same source code.
 * Integration friendly: works with any modern development stack.
-* Lifecycle control: no need to initiate something from outside.
+* Lifecycle control: no need to initiate or to remove something from outside.
 * ESM friendly - native JavaScript modules are best!
 * Developer Experience on the mind: compact & convenient APIs, habitual syntax.
 * Open source (MIT license).
 
 ## 💎 Tech concept keypoints
-* Native modern APIs instead of expensive libraries.
+* Native modern APIs instead of performance-expensive external libraries.
 * Shadow DOM is optional. Use it when you need it only.
 * Total styling freedom: from the old classics to the cutting edge platform abilities.
 * Native HTML instead of custom template syntax processing.
 * Templates are out of the component or render function context. It’s just a simple JavaScript template literals. So you can keep or process them wherever you want.
-* No logical operators in templates. Logic and presentation are strictly separated.
 * Fast synchronous UI updates, no unexpected redraws.
 * Full data context access from the document structure.
 * Full data context availability for template bindings.
 * DOM API friendly approach for the most performant solutions.
 * Convenient object model access instead of opaque abstractions.
+* CDN friendly: every module is a possible endpoint for build or delivery process.
+
+## 🧠 DX
+We believe, that good Developer Experience is not just a vulgar minimum of symbols you typing.
+We believe, that good DX is ability to easily understand, what exactly you see in the code and what exactly you doing. Mental models behind your work are very important for the best result achievement. So, we don't like an excess abstraction layers and the black-box magic compilers.
+
+We build our DX philosophy on these principles:
+* We keep our entities close to platform native ones
+* We don't invent things, which are should be explained on a special developer conference
+* We try to keep maximum similarity between your code and what happens in your runtime
+* We keep in minimum the count of the necessary steps needed to deploy your code
 
 ## 🍏 Quick start
 The easiest way to try Symbiote.js is to create a simple `html` file in your text editor and connect the Symbiote base class from web:
 
 ```html
 <script type="module">
-  import { BaseComponent } from 'https://symbiotejs.github.io/symbiote.js/core/BaseComponent.js';
+  import { Symbiote, html } from 'https://symbiotejs.github.io/symbiote.js/core/Symbiote.js';
 
-  class MyComponent extends BaseComponent {
+  class MyComponent extends Symbiote {
     init$ = {
       count: 0,
       increment: () => {
@@ -67,9 +79,9 @@ The easiest way to try Symbiote.js is to create a simple `html` file in your tex
     }
   }
 
-  MyComponent.template = /*html*/ `
+  MyComponent.template = html`
     <h2>{{count}}</h2>
-    <button set="onclick: increment">Click me!</button>
+    <button ${{onclick: 'increment'}}>Click me!</button>
   `;
 
   MyComponent.reg('my-component');
@@ -100,11 +112,7 @@ Symbiote.js is supported and tested in all major modern desktop and mobile brows
 * Opera
 * etc.
 
-**Internet Explorer** - is outdated and not supported anymore:
-
-https://uploadcare.com/blog/uploadcare-stops-internet-explorer-support/
-
-(But it's possible with polyfills: https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs)
+**Internet Explorer** - is outdated and not supported anymore.
 
 ## 💰 General sponsor
 Big thanks to 🟡 **Uploadcare** for supporting this project!

package/core/AppRouter.js

@@ -1,8 +1,21 @@
 import PubSub from './PubSub.js';
 
 export class AppRouter {
-  /** @private */
-  static _print(msg) {
+
+  /**
+   * @typedef {{title?: String, default?: Boolean, error?: Boolean}} RouteDescriptor
+   */
+
+  /** @type {() => void} */
+  static #onPopstate;
+  /** @type {String} */
+  static #separator;
+  /** @type {String} */
+  static #routingEventName;
+  /** @type {Object<string, RouteDescriptor>} */
+  static appMap = Object.create(null);
+
+  static #print(msg) {
     console.warn(msg);
   }
 
@@ -26,12 +39,12 @@ export class AppRouter {
   /** @param {String} name */
   static set routingEventName(name) {
     /** @private */
-    this.__routingEventName = name;
+    this.#routingEventName = name;
   }
 
   /** @returns {String} */
   static get routingEventName() {
-    return this.__routingEventName || 'sym-on-route';
+    return this.#routingEventName || 'sym-on-route';
   }
 
   static readAddressBar() {
@@ -69,7 +82,7 @@ export class AppRouter {
       this.applyRoute(this.defaultRoute);
       return;
     } else if (!routeScheme) {
-      this._print(`Route "${routeBase.route}" not found...`);
+      this.#print(`Route "${routeBase.route}" not found...`);
       return;
     }
     let event = new CustomEvent(AppRouter.routingEventName, {
@@ -88,7 +101,7 @@ export class AppRouter {
   static reflect(route, options = {}) {
     let routeScheme = this.appMap[route];
     if (!routeScheme) {
-      this._print('Wrong route: ' + route);
+      this.#print('Wrong route: ' + route);
       return;
     }
     let routeStr = '?' + route;
@@ -116,22 +129,22 @@ export class AppRouter {
   /** @param {String} char */
   static setSeparator(char) {
     /** @private */
-    this._separator = char;
+    this.#separator = char;
   }
 
   /** @returns {String} */
   static get separator() {
-    return this._separator || '&';
+    return this.#separator || '&';
   }
 
   /**
    * @param {String} ctxName
-   * @param {Object<string, {}>} routingMap
+   * @param {Object<string, RouteDescriptor>} routingMap
    * @returns {PubSub}
    */
-  static createRouterData(ctxName, routingMap) {
+  static initRoutingCtx(ctxName, routingMap) {
     this.setRoutingMap(routingMap);
-    let routeData = PubSub.registerCtx(
+    let routingCtx = PubSub.registerCtx(
       {
         route: null,
         options: null,
@@ -140,34 +153,32 @@ export class AppRouter {
       ctxName
     );
     window.addEventListener(this.routingEventName, (/** @type {CustomEvent} */ e) => {
-      routeData.multiPub({
-        route: e.detail.route,
+      routingCtx.multiPub({
         options: e.detail.options,
         title: e.detail.options?.title || this.defaultTitle || '',
+        route: e.detail.route,
       });
     });
     AppRouter.notify();
-    this.initPopstateListener();
-    return routeData;
+    this.#initPopstateListener();
+    return routingCtx;
   }
 
-  static initPopstateListener() {
-    if (this.__onPopstate) {
+  static #initPopstateListener() {
+    if (this.#onPopstate) {
       return;
     }
     /** @private */
     this.__onPopstate = () => {
       this.notify();
     };
-    window.addEventListener('popstate', this.__onPopstate);
+    window.addEventListener('popstate', this.#onPopstate);
   }
 
   static removePopstateListener() {
-    window.removeEventListener('popstate', this.__onPopstate);
-    this.__onPopstate = null;
+    window.removeEventListener('popstate', this.#onPopstate);
+    this.#onPopstate = null;
   }
 }
 
-AppRouter.appMap = Object.create(null);
-
 export default AppRouter;

package/core/PubSub.js

@@ -1,5 +1,6 @@
 import { DICT } from './dictionary.js';
 
+// structuredClone() is limited by supported types, so we use custom cloning:
 function cloneObj(obj) {
   let clone = (o) => {
     for (let prop in o) {
@@ -45,7 +46,7 @@ export class PubSub {
       PubSub.#warn('read', prop);
       return null;
     }
-    if (typeof prop === 'string' && prop.includes(DICT.COMPUTED_PX)) {
+    if (typeof prop === 'string' && prop.startsWith(DICT.COMPUTED_PX)) {
       /** @type {Function} */
       let compFn = this.store[prop];
       if (!this.__computedSet) {
@@ -89,6 +90,15 @@ export class PubSub {
       PubSub.#warn('publish', prop);
       return;
     }
+    // @ts-expect-error
+    if (prop?.startsWith(DICT.COMPUTED_PX) && val.constructor !== Function) {
+      PubSub.#warn('publish computed', prop);
+      return;
+    }
+    if (!(this.store[prop] === null || val === null) && typeof this.store[prop] !== typeof val) {
+      // @ts-expect-error
+      console.warn(`Symbiote PubSub: type warning for "${prop}" [${typeof this.store[prop]} -> ${typeof val}]`);
+    }
     this.store[prop] = val;
     this.notify(prop);
   }
@@ -120,7 +130,12 @@ export class PubSub {
   #processComputed() {
     if (this.__computedSet) {
       this.__computedSet.forEach((prop) => {
-        this.notify(prop);
+        if (this[`__${prop}_timeout`]) {
+          window.clearTimeout(this[`__${prop}_timeout`]);
+        }
+        this[`__${prop}_timeout`] = window.setTimeout(() => {
+          this.notify(prop);
+        });
       });
     }
   }
@@ -131,9 +146,9 @@ export class PubSub {
       this.callbackMap[prop].forEach((callback) => {
         callback(this.read(prop));
       });
-      // @ts-expect-error
-      !prop?.startsWith(DICT.COMPUTED_PX) && this.#processComputed();
     }
+    // @ts-expect-error
+    !prop?.startsWith(DICT.COMPUTED_PX) && this.#processComputed();
   }
 
   /**

package/core/README.md

@@ -3,23 +3,29 @@
 ### index.js
 All-in-one exports.
 
-### BaseComponent.js
+### Symbiote.js
 Base component class. Major utility for the web-component creation, template data binding and data management.
 
 ### html.js
-Template literal tag function, that transforms interpolated binding descriptions into resulting html.
+Template literal tag-function, that transforms interpolated binding descriptions into resulting html.
 
-### Data.js
+### css.js
+Template literal tag-function, that creates the CSSStyleSheet instance.
+
+### PubSub.js
 Implements data layer for the local component context and the top level context both. The state management approach is based on simple well known pub/sub pattern.
 
 ### AppRouter.js
-SPA routing utility. Based on native History API.
+SPA routing utility. Based on browser-native History API.
 
 ### tpl-rpcessors.js
 Template processing functions. Implements basic template processing flow.
 
-### repeatProcessor.js
-Dynamic list rendering implementation.
+### itemizeProcessor.js
+Dynamic list items rendering implementation.
 
 ### dictionary.js
-Dictionary for the set of the basic keys.
+Dictionary for the set of the basic keys.
+
+### slotProcessor.js
+Light DOM support for the template `slot`s. This processor is optional since 2.x. and excluded from default template processing pipeline.

package/core/{BaseComponent.js → Symbiote.js}

@@ -7,22 +7,21 @@ import { prepareStyleSheet } from '../utils/prepareStyleSheet.js';
 import PROCESSORS from './tpl-processors.js';
 import { parseCssPropertyValue } from '../utils/parseCssPropertyValue.js';
 
-let autoTagsCount = 0;
-
-/** @type {MutationObserver} */
-let styleMutationObserver = null;
+export { html } from './html.js';
+export { css } from './css.js';
+export { UID, PubSub }
 
-/** @type {Set<() => void>} */
-let styleMutationObserverCbList = null;
+let autoTagsCount = 0;
 
 /** @template S */
-export class BaseComponent extends HTMLElement {
+export class Symbiote extends HTMLElement {
   /** @type {Boolean} */
   #initialized;
   /** @type {String} */
   #autoCtxName;
   /** @type {String} */
   #cachedCtxName;
+  /** @type {PubSub} */
   #localCtx;
   #stateProxy;
   /** @type {Boolean} */
@@ -32,15 +31,15 @@ export class BaseComponent extends HTMLElement {
   #computedStyle;
   #boundCssProps;
 
-  /** @type {typeof BaseComponent} */
-  // @ts-ignore
+  /** @type {typeof Symbiote} */
+  // @ts-expect-error
   #super = this.constructor;
 
   /** @type {HTMLTemplateElement} */
   static __tpl;
 
-  get BaseComponent() {
-    return BaseComponent;
+  get Symbiote() {
+    return Symbiote;
   }
 
   initCallback() {}
@@ -70,14 +69,14 @@ export class BaseComponent extends HTMLElement {
       });
     }
     if (this.allowCustomTemplate) {
-      let customTplSelector = this.getAttribute(DICT.USE_TPL);
+      let customTplSelector = this.getAttribute(DICT.USE_TPL_ATTR);
       if (customTplSelector) {
         let root = this.getRootNode();
         /** @type {HTMLTemplateElement} */
-        // @ts-ignore
+        // @ts-expect-error
         let customTpl = root?.querySelector(customTplSelector) || document.querySelector(customTplSelector);
         if (customTpl) {
-          // @ts-ignore
+          // @ts-expect-error
           template = customTpl.content.cloneNode(true);
         } else {
           console.warn(`Symbiote template "${customTplSelector}" is not found...`);
@@ -99,10 +98,10 @@ export class BaseComponent extends HTMLElement {
       } else if (template?.constructor === String) {
         let tpl = document.createElement('template');
         tpl.innerHTML = template;
-        // @ts-ignore
+        // @ts-expect-error
         fr = tpl.content.cloneNode(true);
       } else if (this.#super.__tpl) {
-        // @ts-ignore
+        // @ts-expect-error
         fr = this.#super.__tpl.content.cloneNode(true);
       }
       for (let fn of this.tplProcessors) {
@@ -129,7 +128,7 @@ export class BaseComponent extends HTMLElement {
   }
 
   /**
-   * @template {BaseComponent} T
+   * @template {Symbiote} T
    * @param {(fr: DocumentFragment | T, fnCtx: T) => void} processorFn
    */
   addTemplateProcessor(processorFn) {
@@ -140,9 +139,9 @@ export class BaseComponent extends HTMLElement {
     super();
     /** @type {S} */
     this.init$ = Object.create(null);
-    /** @type {Object<string, any>} */
+    /** @type {Object<string, *>} */
     this.cssInit$ = Object.create(null);
-    /** @type {Set<(fr: DocumentFragment | BaseComponent, fnCtx: unknown) => void>} */
+    /** @type {Set<(fr: DocumentFragment | Symbiote, fnCtx: unknown) => void>} */
     this.tplProcessors = new Set();
     /** @type {Object<string, any>} */
     this.ref = Object.create(null);
@@ -156,6 +155,8 @@ export class BaseComponent extends HTMLElement {
     /** @type {Boolean} */
     this.processInnerHtml = false;
     /** @type {Boolean} */
+    this.ssrMode = false;
+    /** @type {Boolean} */
     this.allowCustomTemplate = false;
     /** @type {Boolean} */
     this.ctxOwner = false;
@@ -198,12 +199,12 @@ export class BaseComponent extends HTMLElement {
   }
 
   /** @returns {PubSub} */
-  get nodeCtx() {
+  get sharedCtx() {
     return PubSub.getCtx(this.ctxName, false) || PubSub.registerCtx({}, this.ctxName);
   }
 
   /**
-   * @template {BaseComponent} T
+   * @template {Symbiote} T
    * @param {String} prop
    * @param {T} fnCtx
    */
@@ -213,20 +214,26 @@ export class BaseComponent extends HTMLElement {
     /** @type {String} */
     let name;
     if (prop.startsWith(DICT.SHARED_CTX_PX)) {
-      ctx = fnCtx.nodeCtx;
+      ctx = fnCtx.sharedCtx;
       name = prop.replace(DICT.SHARED_CTX_PX, '');
     } else if (prop.startsWith(DICT.PARENT_CTX_PX)) {
       name = prop.replace(DICT.PARENT_CTX_PX, '');
       let found = fnCtx;
       while (found && !found?.has?.(name)) {
-        // @ts-ignore
-        found = found.parentElement;
+        // @ts-expect-error
+        found = found.parentElement || found.parentNode || found.host;
       }
       ctx = found?.localCtx || fnCtx.localCtx;
     } else if (prop.includes(DICT.NAMED_CTX_SPLTR)) {
       let pArr = prop.split(DICT.NAMED_CTX_SPLTR);
       ctx = PubSub.getCtx(pArr[0]);
       name = pArr[1];
+    } else if (prop.startsWith(DICT.CSS_DATA_PX)) {
+      ctx = fnCtx.localCtx;
+      name = prop;
+      if (!ctx.has(name)) {
+        fnCtx.bindCssData(name);
+      }
     } else {
       ctx = fnCtx.localCtx;
       name = prop;
@@ -245,12 +252,12 @@ export class BaseComponent extends HTMLElement {
    */
   sub(prop, handler, init = true) {
     let subCb = (val) => {
-      if (!this.isVirtual && !this.isConnected) {
+      if (this.#noInit) {
         return;
       }
       handler(val);
     };
-    let parsed = BaseComponent.#parseProp(/** @type {string} */ (prop), this);
+    let parsed = Symbiote.#parseProp(/** @type {string} */ (prop), this);
     if (!parsed.ctx.has(parsed.name)) {
       // Avoid *prop binding race:
       window.setTimeout(() => {
@@ -263,13 +270,13 @@ export class BaseComponent extends HTMLElement {
 
   /** @param {String} prop */
   notify(prop) {
-    let parsed = BaseComponent.#parseProp(prop, this);
+    let parsed = Symbiote.#parseProp(prop, this);
     parsed.ctx.notify(parsed.name);
   }
 
   /** @param {String} prop */
   has(prop) {
-    let parsed = BaseComponent.#parseProp(prop, this);
+    let parsed = Symbiote.#parseProp(prop, this);
     return parsed.ctx.has(parsed.name);
   }
 
@@ -280,7 +287,7 @@ export class BaseComponent extends HTMLElement {
    * @param {Boolean} [rewrite]
    */
   add(prop, val, rewrite = false) {
-    let parsed = BaseComponent.#parseProp(prop, this);
+    let parsed = Symbiote.#parseProp(prop, this);
     parsed.ctx.add(parsed.name, val, rewrite);
   }
 
@@ -300,12 +307,12 @@ export class BaseComponent extends HTMLElement {
       let o = Object.create(null);
       this.#stateProxy = new Proxy(o, {
         set: (obj, /** @type {String} */ prop, val) => {
-          let parsed = BaseComponent.#parseProp(prop, this);
+          let parsed = Symbiote.#parseProp(prop, this);
           parsed.ctx.pub(parsed.name, val);
           return true;
         },
         get: (obj, /** @type {String} */ prop) => {
-          let parsed = BaseComponent.#parseProp(prop, this);
+          let parsed = Symbiote.#parseProp(prop, this);
           return parsed.ctx.read(parsed.name);
         },
       });
@@ -346,7 +353,7 @@ export class BaseComponent extends HTMLElement {
     }
     for (let prop in this.init$) {
       if (prop.startsWith(DICT.SHARED_CTX_PX)) {
-        this.nodeCtx.add(prop.replace(DICT.SHARED_CTX_PX, ''), this.init$[prop], this.#ctxOwner);
+        this.sharedCtx.add(prop.replace(DICT.SHARED_CTX_PX, ''), this.init$[prop], this.#ctxOwner);
       } else if (prop.includes(DICT.NAMED_CTX_SPLTR)) {
         let propArr = prop.split(DICT.NAMED_CTX_SPLTR);
         let ctxName = propArr[0].trim();
@@ -368,10 +375,14 @@ export class BaseComponent extends HTMLElement {
     this.#dataCtxInitialized = true;
   }
 
-  connectedCallback() {
+  get #noInit() {
+    return !this.isVirtual && !this.isConnected;
+  }
+
+  #initComponent() {
     // As `connectedCallback` calls are queued, it could be called after element being detached from DOM
     // See example at https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-conformance
-    if (!this.isVirtual && !this.isConnected) {
+    if (this.#noInit) {
       return;
     }
     if (this.#disconnectTimeout) {
@@ -398,7 +409,7 @@ export class BaseComponent extends HTMLElement {
       } else {
         if (this.#super.rootStyleSheets) {
           /** @type {Document | ShadowRoot} */
-          // @ts-ignore
+          // @ts-expect-error
           let root = this.getRootNode();
           if (!root) {
             return;
@@ -412,6 +423,10 @@ export class BaseComponent extends HTMLElement {
     this.connectedOnce = true;
   }
 
+  connectedCallback() {
+    this.#initComponent();
+  }
+
   destroyCallback() {}
 
   disconnectedCallback() {
@@ -435,12 +450,6 @@ export class BaseComponent extends HTMLElement {
       for (let proc of this.tplProcessors) {
         this.tplProcessors.delete(proc);
       }
-      styleMutationObserverCbList?.delete(this.updateCssData);
-      if (!styleMutationObserverCbList?.size) {
-        styleMutationObserver?.disconnect();
-        styleMutationObserver = null;
-        styleMutationObserverCbList = null;
-      }
     }, 100);
   }
 
@@ -544,27 +553,6 @@ export class BaseComponent extends HTMLElement {
     });
   };
 
-  #initStyleAttrObserver() {
-    if (!styleMutationObserverCbList) {
-      styleMutationObserverCbList = new Set();
-    }
-    styleMutationObserverCbList.add(this.updateCssData);
-    if (!styleMutationObserver) {
-      styleMutationObserver = new MutationObserver((/** @type {MutationRecord[]} */ records) => {
-        records[0].type === 'attributes' &&
-          styleMutationObserverCbList.forEach((cb) => {
-            cb();
-          });
-      });
-      styleMutationObserver.observe(document, {
-        childList: true,
-        subtree: true,
-        attributes: true,
-        attributeFilter: ['style'],
-      });
-    }
-  }
-
   /**
    * @param {String} propName
    * @param {any} [initValue] Uses empty string by default to make value useful in template
@@ -576,8 +564,10 @@ export class BaseComponent extends HTMLElement {
     this.#boundCssProps.add(propName);
     let val = this.getCssData(this.#extractCssName(propName), true);
     val === null && (val = initValue);
-    this.add(propName, val);
-    this.#initStyleAttrObserver();
+    propName.startsWith(DICT.CSS_DATA_PX) 
+      // To prevent prop name parsing in cycle:
+      ? this.localCtx.add(propName, val) 
+      : this.add(propName, val);
   }
 
   dropCssDataCache() {
@@ -640,4 +630,4 @@ export class BaseComponent extends HTMLElement {
   }
 }
 
-export default BaseComponent;
+export default Symbiote;

package/core/css.js

@@ -3,8 +3,32 @@
  * @returns {CSSStyleSheet}
  */
 
-export function css(parts) {
+export function css(parts, ...props) {
+  let cssTxt = '';
   let sheet = new CSSStyleSheet();
-  sheet.replaceSync(parts.join(''));
+  parts.forEach((part, idx) => {
+    cssTxt += part + props[idx];
+  });
+  css.processors.forEach((prFn) => {
+    cssTxt = prFn(cssTxt);
+  });
+  css.clearProcessors();
+  sheet.replaceSync(cssTxt);
   return sheet;
-}
+}
+
+/** @type {((cssTxt: string) => String)[]} */
+css.processors = [];
+
+css.clearProcessors = function() {
+  css.processors = [];
+}
+
+/**
+ * 
+ * @param  {...(cssTxt: string) => String} args 
+ */
+css.useProcessor = function(...args) {
+  css.processors = [...css.processors, ...args];
+  return css;
+};