npm - web-signature - Versions diffs - 0.2.6 → 0.2.9 - Mend

web-signature 0.2.6 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.MD +5 -0
package/bundle/d/index.d.ts +37 -3
package/bundle/index.js +52 -1
package/bundle/index.min.js +1 -1
package/dist/Component.js +2 -0
package/dist/Plugin.js +2 -0
package/dist/Signature.js +45 -0
package/dist/d/Component.d.ts +2 -0
package/dist/d/Plugin.d.ts +12 -0
package/dist/d/Signature.d.ts +10 -0
package/dist/d/html.d.ts +6 -2
package/dist/d/index.d.ts +1 -0
package/dist/d/types/Component.d.ts +8 -0
package/dist/d/types/MetaPlugin.d.ts +5 -0
package/dist/html.js +13 -0
package/dist/index.js +1 -0
package/dist/types/MetaPlugin.js +1 -0
package/package.json +1 -1
package/src/Component.ts +4 -0
package/src/Plugin.ts +13 -0
package/src/Signature.ts +61 -2
package/src/html.ts +25 -4
package/src/index.ts +2 -1
package/src/types/Component.ts +9 -0
package/src/types/MetaPlugin.ts +6 -0

package/README.MD CHANGED Viewed

@@ -31,12 +31,17 @@ npm run dev
 * [Signature](#signature)
 * [Quick Start](#quick-start)
+	* [Try online](#try-online)
 * [Introduction](#introduction)
 	* [Briefly about Signature](#briefly-about-signature)
 	* [About Component](#about-component)
 	* [Quick about the Library](#quick-about-the-library)
 	* [See more here](#see-more-here)
+## Try online
+You can also try Signature online using [StackBlitz](https://stackblitz.com/fork/signature-starter)
 # Introduction
 Signature uses four classes as its basis:

package/bundle/d/index.d.ts CHANGED Viewed

@@ -66,6 +66,10 @@ interface Component$1 {
      * Optional content that is specified in the component tag.
      */
     content?: string;
+    /**
+     * Optional groups that the component belongs to.
+     */
+    groups: string[];
     /**
      * Defining component properties.
      */
@@ -74,6 +78,10 @@ interface Component$1 {
      * The properties of the component.
      */
     data: Record<string, string | number | boolean | null>;
+    /**
+     * Plugins are stored here.
+     */
+    $: Record<string, unknown>;
     /**
      * Returns the component as a string (template).
      * @returns {html | Promise<html>} The rendered component as a string (template).
@@ -112,10 +120,12 @@ interface Component$1 {
 declare abstract class Component implements Component$1 {
     abstract readonly name: string;
     content?: string;
+    groups: string[];
     options: Options;
     ref?: Ref;
     readonly props: Record<string, Prop$1>;
     readonly data: Record<string, string | number | boolean | null>;
+    $: Record<string, unknown>;
     abstract render(): html$1 | Promise<html$1>;
     onInit?(): void;
     onRender?(): void;
@@ -180,6 +190,19 @@ declare class Library {
     }>;
 }
+declare abstract class Plugin {
+    /**
+     * Modules are mini plugins that are required for the plugin to work, they are processed and stored before the plugin itself is installed and stored in a safe place.
+     */
+    readonly abstract modules: Record<string, () => Record<string, unknown>>;
+    /**
+     * The function returns an object that will be installed as a plugin in Signature.$
+     * @param modules
+     * @returns {Record<string, unknown>} The object that will be installed as a plugin
+     */
+    abstract define(modules: Record<string, Record<string, unknown>>): Record<string, unknown>;
+}
 type ResolvedLib = {
     components: string[];
     dependencies: Record<string, ResolvedLib>;
@@ -189,6 +212,8 @@ declare class Signature {
     private refs;
     private libs;
     private bank;
+    private $;
+    private $g;
     constructor();
     /**
      * Adds a component to the signature.
@@ -214,6 +239,13 @@ declare class Signature {
      * @return {Record<string, ResolvedLib>} A object of formatted libraries with their components and dependencies.
      */
     libraries(): Record<string, ResolvedLib>;
+    /**
+     * Registers a plugin in the signature.
+     * @import {Plugin} from "./Plugin.js";
+     * @param {string} name The name of the plugin.
+     * @param {Plugin} plugin The plugin to register.
+     */
+    use(name: string, plugin: Plugin): void;
     /**
      * Contacts the Component.onContact method through its reference.
      * @param {string} name The name of the reference.
@@ -252,15 +284,17 @@ declare class Prop<T extends keyof TypesMap> implements Prop$1 {
     isValid(value: TypesMap[keyof TypesMap]): boolean;
 }
-declare function html(strings: TemplateStringsArray, ...values: any[]): {
+type HTMLTemplate = {
     strings: TemplateStringsArray;
     values: any[];
 };
-declare function unsafeHTML(value: any): {
+declare function html(strings: TemplateStringsArray, ...values: any[]): HTMLTemplate;
+type unsafeHTMLTemplate = {
     type: "unsafeHTML";
     value: any;
 };
+declare function unsafeHTML(value: any): unsafeHTMLTemplate;
 declare function export_default(): Signature;
-export { Component, Library, Prop, Signature, export_default as default, html, unsafeHTML };
+export { Component, Library, Plugin, Prop, Signature, export_default as default, html, unsafeHTML };

package/bundle/index.js CHANGED Viewed

@@ -26,6 +26,8 @@ class Signature {
     refs = {};
     libs = {};
     bank = new Map();
+    $ = {};
+    $g = {};
     constructor() {
     }
     /**
@@ -99,6 +101,26 @@ class Signature {
         };
         return resolve(this.libs);
     }
+    /**
+     * Registers a plugin in the signature.
+     * @import {Plugin} from "./Plugin.js";
+     * @param {string} name The name of the plugin.
+     * @param {Plugin} plugin The plugin to register.
+     */
+    use(name, plugin) {
+        if (this.$[name]) {
+            throw new Error(`Plugin with name ${name} already exists.`);
+        }
+        let modules = {};
+        Object.keys(plugin.modules).forEach((key) => {
+            modules[key] = plugin.modules[key]();
+        });
+        this.$[name] = {
+            plugin: plugin.define(modules),
+            modules
+        };
+        this.$g[name] = this.$[name].plugin;
+    }
     /**
      * Contacts the Component.onContact method through its reference.
      * @param {string} name The name of the reference.
@@ -153,6 +175,15 @@ class Signature {
                 throw new Error(`Component '${component.name}' must render a single root element.`);
             }
             const newElement = template.content.firstElementChild;
+            // Preserve old ref attribute
+            let oldRef = ref.element.getAttribute("ref");
+            if (oldRef) {
+                newElement.setAttribute("ref", oldRef);
+            }
+            // Preserve si-group attribute
+            if (component.groups.length > 0) {
+                newElement.setAttribute("si-group", component.groups.join(" "));
+            }
             this.render(template.content);
             component.onRender?.(); // lifecycle hook
             ref.element.replaceWith(newElement);
@@ -286,6 +317,8 @@ class Signature {
             // Find all elements with the component name in the frame
             for (const el of Array.from(frame.querySelectorAll(com)).concat(Array.from(frame.querySelectorAll(`[si-component="${com}"]`)))) {
                 const renderer = new component();
+                renderer.$ = this.$g; // injecting plugins
+                Object.freeze(renderer.$); // prevent plugins from being modified by components
                 renderer.onInit?.(); // lifecycle hook
                 if (el instanceof HTMLElement) {
                     // Fill the renderer's content
@@ -411,6 +444,10 @@ class Signature {
                     this.render(body.content);
                     renderer.onRender?.(); // lifecycle hook
                     const mountEl = body.firstElementChild;
+                    // Processing group
+                    if (renderer?.groups.length > 0) {
+                        mountEl.setAttribute("si-group", renderer.groups.join(" "));
+                    }
                     // Processing ref
                     if (el.hasAttribute("ref") || renderer.options.generateRefIfNotSpecified) {
                         let refName = el.getAttribute("ref");
@@ -433,6 +470,14 @@ class Signature {
                             update: () => this.updateRef(refName)
                         };
                     }
+                    // Copying another attributes from the original element to the new one, with exceptions
+                    for (const attr of Array.from(el.attributes)) {
+                        const name = attr.name;
+                        if (renderer.props[name] !== undefined || name === "ref" || name === "si-component" || name === "si-group")
+                            continue;
+                        if (!mountEl.hasAttribute(name))
+                            mountEl.setAttribute(name, attr.value);
+                    }
                     el.replaceWith(body.firstElementChild);
                     renderer.onMount?.(mountEl); // lifecycle hook
                 });
@@ -443,12 +488,14 @@ class Signature {
 class Component {
     content;
+    groups = [];
     options = {
         generateRefIfNotSpecified: false,
     };
     ref;
     props = {};
     data = {};
+    $ = {};
     onInit() {
     }
     ;
@@ -586,9 +633,13 @@ function html(strings, ...values) {
 function unsafeHTML(value) {
     return { type: "unsafeHTML", value: value };
 }
+// todo: make a loop function
+class Plugin {
+}
 function index () {
     return new Signature();
 }
-export { Component, Library, Prop, Signature, index as default, html, unsafeHTML };
+export { Component, Library, Plugin, Prop, Signature, index as default, html, unsafeHTML };

package/bundle/index.min.js CHANGED Viewed

	@@ -1 +1 @@
1	- class e{element;instance;constructor(e,t){this.instance=e,this.element=t}}const t={"element-not-found":"Element not found for selector: #selector","prop-is-required":"Property '#prop' in component '#component' is required but not provided.","unsupported-type-for-property":"Unsupported type for property '#prop' in component '#component': #type","invalid-value-for-property":"Invalid value for property '#prop' in component '#component': #value (value: #attr)","multiple-root-elements":"Component '#component' must render a single root element. \n\t#elements","ref-collision":"Ref collision detected for ref '#ref' in component '#component'.",unknown:"An unknown error occurred.","unknown-from":"An unknown error occurred in component '#from'.","stack-overflow":"Stack Overflow detected: possible recursive component rendering.","render-async-failed":"Error during asynchronous rendering of the component #component."};let n=0;class r{components={};refs={};libs={};bank=new Map;constructor(){}add(e,t){const n="string"==typeof t?t:e.name;this.components[n]&&console.warn(new Error(`Component with name ${n} already exists.`)),this.components[n]=e}register(e,...t){this.libs[e.name]&&console.warn(new Error(`Library with name ${e.name} already exists.`));const n=e.list().filter(e=>!(e.name in t));this.libs[e.name]={name:e.name,version:e.version,author:e.author,components:n.map(e=>e.name),dependencies:e.libs};for(const t of n)this.add(t.component,`${e.name}-${t.name}`)}lib(e){return this.libs[e]}libraries(){const e=e=>{let t=e.name;return e.version&&(t+=`@${e.version}`),e.author&&(t+=`#${e.author}`),t},t=(n,r=new Set)=>{const o={};for(const[s,i]of Object.entries(n)){const n=e(i);r.has(n)\|\|(r.add(n),o[n]={components:i.components,dependencies:t(i.dependencies,r)})}return o};return t(this.libs)}contactWith(e,...t){const n=this.refs[e];if(!n)throw new Error(`Ref with name ${e} does not exist.`);const r=n.instance;return r.onContact?.(...t)}updateRef(e){const t=this.refs[e];if(!t)throw new Error(`Ref with name ${e} does not exist.`);const n=t.instance;let r={strings:Object.assign([],{raw:[]}),values:[]};try{r=n.render()}catch(e){if(e instanceof Error)throw{id:"unknown-from",from:n.name,err:e}}const o=document.createElement("template");(e=>{r instanceof Promise?r.then(t=>{o.content.appendChild(this.templateToElement(t,n.name)),e()}).catch(e=>{throw{id:"unknown-from",from:n.name,err:e}}):"object"==typeof r&&(o.content.appendChild(this.templateToElement(r,n.name)),e())})(()=>{if(1!==o.content.children.length)throw new Error(`Component '${n.name}' must render a single root element.`);const e=o.content.firstElementChild;this.render(o.content),n.onRender?.(),t.element.replaceWith(e),t.element=e,n.onMount?.(e)})}contact(e,n){new Promise((t,r)=>{try{const t=document.querySelector(e);if(!t)return void r({id:"element-not-found",selector:e});const o=document.createElement("div");o.innerHTML=t.innerHTML,this.render(o),t.replaceChildren(...Array.from(o.childNodes)),n&&n()}catch(e){e instanceof Error?e instanceof RangeError&&e.message.includes("stack")?r({id:"stack-overflow",err:e}):r({id:"unknown",err:e}):r(e)}}).catch(e=>{let n=t[e.id];throw Object.keys(e).filter(e=>!(e in["id","err"])).forEach(t=>{n=n.replace(new RegExp(`#${t}`,"gm"),String(e[t]))}),window.SIGNATURE?.DEV_MODE&&console.log(e),e.id in["unknown","unknown-from","render-async-failed"]?console.error(`[${e.id}] ${n}`,e.err):console.error(`[${e.id}] ${n}`),"Page rendering was interrupted by Signature due to the above error."})}templateToString(e){let t="";for(let n=0;n<e.strings.length;n++)t+=e.strings[n],n<e.values.length&&(t+=`\x3c!--si-mark-${n}--\x3e`);return t}fillTemplate(e,t){let n;return this.bank.has(e.strings.join("@@"))?n=this.bank.get(e.strings.join("@@"))?.cloneNode(!0):(n=document.createElement("template"),n.innerHTML=t,this.bank.set(e.strings.join("@@"),n.cloneNode(!0))),(()=>{let t,r=document.createTreeWalker(n.content,NodeFilter.SHOW_COMMENT),o=[];for(;t=r.nextNode();)/si-mark-\d+/gm.test(t.nodeValue??"")&&o.push(t);for(const t of o){const n=e.values[Number((t.nodeValue??"").match(/si-mark-(\d+)/m)[1])];if("object"==typeof n&&"unsafeHTML"===n.type){let e=document.createElement("div");for(e.innerHTML=n.value;e.firstChild;)t.parentNode?.insertBefore(e.firstChild,t);t.remove()}else t.replaceWith(document.createTextNode(String(n)))}})(),(()=>{let t,r=document.createTreeWalker(n.content,NodeFilter.SHOW_ELEMENT);for(;t=r.nextNode();)for(const n of Array.from(t.attributes))if(/<!--si-mark-\d+-->/gm.test(n.value)){const r=n.value.match(/si-mark-(\d+)/m);if(r){const o=e.values[Number(r[1])];t.setAttribute(n.name,String(o))}}})(),n}templateToElement(e,t){const n=this.templateToString(e),r=this.fillTemplate(e,n);if(1!==r.content.children.length)throw{id:"multiple-root-elements",elements:r.innerHTML,component:t};return r.content.firstElementChild}render(t){for(const r of Object.keys(this.components)){const o=this.components[r];for(const s of Array.from(t.querySelectorAll(r)).concat(Array.from(t.querySelectorAll(`[si-component="${r}"]`)))){const t=new o;if(t.onInit?.(),s instanceof HTMLElement){t.content=s.innerHTML.trim();for(const e of Object.keys(t.props)){const n=s.getAttribute(e);if(null===n){if(t.props[e].required)throw{id:"prop-is-required",component:r,prop:e};t.data[e]=null}else if(""===n){if(t.props[e].required)throw{id:"prop-is-required",component:r,prop:e};t.props[e].isValid(n)&&(t.data[e]=null)}else{let o;switch(t.props[e].type){case"boolean":o=Boolean(n);break;case"number":o=Number(n);break;case"string":o=String(n);break;case"array":try{o=JSON.parse(n)}catch(t){throw{id:"invalid-value-for-property",component:r,prop:e,value:n,attr:n}}break;default:if(t.props[e].required)throw{id:"unsupported-type-for-property",component:r,prop:e,type:t.props[e].type}}if(void 0!==o){if(!t.props[e].isValid(o))throw{id:"invalid-value-for-property",component:r,prop:e,value:o,attr:n};if(t.props[e].validate&&!t.props[e].validate(o))throw{id:"invalid-value-for-property",component:r,prop:e,value:o,attr:n};t.data[e]=o,t.onPropParsed?.(t.props[e],o)}}}t.onPropsParsed?.()}const i=document.createElement("template");let a={strings:Object.assign([],{raw:[]}),values:[]};try{a=t.render()}catch(e){if(e instanceof Error)throw{id:"unknown-from",from:t.name,err:e}}(e=>{if(a instanceof Promise)try{a.then(t=>{i.appendChild(this.templateToElement(t,r)),e()}).catch(e=>{throw{id:"unknown-from",from:t.name,err:e}})}catch(e){throw{id:"render-async-failed",component:r,err:e}}else"object"==typeof a&&(i.appendChild(this.templateToElement(a,r)),e())})(()=>{this.render(i.content),t.onRender?.();const o=i.firstElementChild;if(s.hasAttribute("ref")\|\|t.options.generateRefIfNotSpecified){let i=s.getAttribute("ref");if(null===i&&(i=""),n++,""===i&&(i=`r${n}${Math.random().toString(36).substring(2,15)}${n}`),this.refs[i])throw{id:"ref-collision",ref:i,component:r};this.refs[i]=new e(t,o),o.setAttribute("ref",i),t.ref={id:i,contact:(...e)=>this.contactWith(i,...e),update:()=>this.updateRef(i)}}s.replaceWith(i.firstElementChild),t.onMount?.(o)})}}}}class o{content;options={generateRefIfNotSpecified:!1};ref;props={};data={};onInit(){}onRender(){}onMount(e){}onContact(...e){}onPropsParsed(){}onPropParsed(e,t){}}class s{type;required=!0;validate;constructor(e,t=!0,n){this.type=e,this.required=t,this.validate=n\|\|(()=>!0)}isValid(e){switch(this.type){case"boolean":return"boolean"==typeof e;case"number":return"number"==typeof e&&!isNaN(e);case"string":return"string"==typeof e;case"array":return Array.isArray(e);case"null":return null===e;default:return!1}}}class i{name;version;author;libs={};components={};constructor(e,t,n){this.name=e,this.author=t,this.version=n}add(e,t){const n="string"==typeof t?t:e.name;this.components[n]&&console.warn(new Error(`Component with name ${n} already exists.`)),this.components[n]=e}register(e,...t){this.libs[e.name]&&console.warn(new Error(`Library with name ${e.name} already exists in ${this.name}.`));const n=e.list().filter(e=>!(e.name in t));this.libs[e.name]={name:e.name,version:e.version,author:e.author,components:n.map(e=>e.name),dependencies:e.libs};for(const t of n)this.add(t.component,`${e.name}-${t.name}`)}get(e){return this.components[e]}lib(e){return this.libs[e]}list(){return Object.entries(this.components).map(([e,t])=>({component:t,name:e}))}}function a(e,...t){return{strings:e,values:t}}function c(e){return{type:"unsafeHTML",value:e}}function l(){return new r}export{o as Component,i as Library,s as Prop,r as Signature,l as default,a as html,c as unsafeHTML};
1	+ class e{element;instance;constructor(e,t){this.instance=e,this.element=t}}const t={"element-not-found":"Element not found for selector: #selector","prop-is-required":"Property '#prop' in component '#component' is required but not provided.","unsupported-type-for-property":"Unsupported type for property '#prop' in component '#component': #type","invalid-value-for-property":"Invalid value for property '#prop' in component '#component': #value (value: #attr)","multiple-root-elements":"Component '#component' must render a single root element. \n\t#elements","ref-collision":"Ref collision detected for ref '#ref' in component '#component'.",unknown:"An unknown error occurred.","unknown-from":"An unknown error occurred in component '#from'.","stack-overflow":"Stack Overflow detected: possible recursive component rendering.","render-async-failed":"Error during asynchronous rendering of the component #component."};let n=0;class r{components={};refs={};libs={};bank=new Map;$={};$g={};constructor(){}add(e,t){const n="string"==typeof t?t:e.name;this.components[n]&&console.warn(new Error(`Component with name ${n} already exists.`)),this.components[n]=e}register(e,...t){this.libs[e.name]&&console.warn(new Error(`Library with name ${e.name} already exists.`));const n=e.list().filter(e=>!(e.name in t));this.libs[e.name]={name:e.name,version:e.version,author:e.author,components:n.map(e=>e.name),dependencies:e.libs};for(const t of n)this.add(t.component,`${e.name}-${t.name}`)}lib(e){return this.libs[e]}libraries(){const e=e=>{let t=e.name;return e.version&&(t+=`@${e.version}`),e.author&&(t+=`#${e.author}`),t},t=(n,r=new Set)=>{const o={};for(const[s,i]of Object.entries(n)){const n=e(i);r.has(n)\|\|(r.add(n),o[n]={components:i.components,dependencies:t(i.dependencies,r)})}return o};return t(this.libs)}use(e,t){if(this.$[e])throw new Error(`Plugin with name ${e} already exists.`);let n={};Object.keys(t.modules).forEach(e=>{n[e]=t.modules[e]()}),this.$[e]={plugin:t.define(n),modules:n},this.$g[e]=this.$[e].plugin}contactWith(e,...t){const n=this.refs[e];if(!n)throw new Error(`Ref with name ${e} does not exist.`);const r=n.instance;return r.onContact?.(...t)}updateRef(e){const t=this.refs[e];if(!t)throw new Error(`Ref with name ${e} does not exist.`);const n=t.instance;let r={strings:Object.assign([],{raw:[]}),values:[]};try{r=n.render()}catch(e){if(e instanceof Error)throw{id:"unknown-from",from:n.name,err:e}}const o=document.createElement("template");(e=>{r instanceof Promise?r.then(t=>{o.content.appendChild(this.templateToElement(t,n.name)),e()}).catch(e=>{throw{id:"unknown-from",from:n.name,err:e}}):"object"==typeof r&&(o.content.appendChild(this.templateToElement(r,n.name)),e())})(()=>{if(1!==o.content.children.length)throw new Error(`Component '${n.name}' must render a single root element.`);const e=o.content.firstElementChild;let r=t.element.getAttribute("ref");r&&e.setAttribute("ref",r),n.groups.length>0&&e.setAttribute("si-group",n.groups.join(" ")),this.render(o.content),n.onRender?.(),t.element.replaceWith(e),t.element=e,n.onMount?.(e)})}contact(e,n){new Promise((t,r)=>{try{const t=document.querySelector(e);if(!t)return void r({id:"element-not-found",selector:e});const o=document.createElement("div");o.innerHTML=t.innerHTML,this.render(o),t.replaceChildren(...Array.from(o.childNodes)),n&&n()}catch(e){e instanceof Error?e instanceof RangeError&&e.message.includes("stack")?r({id:"stack-overflow",err:e}):r({id:"unknown",err:e}):r(e)}}).catch(e=>{let n=t[e.id];throw Object.keys(e).filter(e=>!(e in["id","err"])).forEach(t=>{n=n.replace(new RegExp(`#${t}`,"gm"),String(e[t]))}),window.SIGNATURE?.DEV_MODE&&console.log(e),e.id in["unknown","unknown-from","render-async-failed"]?console.error(`[${e.id}] ${n}`,e.err):console.error(`[${e.id}] ${n}`),"Page rendering was interrupted by Signature due to the above error."})}templateToString(e){let t="";for(let n=0;n<e.strings.length;n++)t+=e.strings[n],n<e.values.length&&(t+=`\x3c!--si-mark-${n}--\x3e`);return t}fillTemplate(e,t){let n;return this.bank.has(e.strings.join("@@"))?n=this.bank.get(e.strings.join("@@"))?.cloneNode(!0):(n=document.createElement("template"),n.innerHTML=t,this.bank.set(e.strings.join("@@"),n.cloneNode(!0))),(()=>{let t,r=document.createTreeWalker(n.content,NodeFilter.SHOW_COMMENT),o=[];for(;t=r.nextNode();)/si-mark-\d+/gm.test(t.nodeValue??"")&&o.push(t);for(const t of o){const n=e.values[Number((t.nodeValue??"").match(/si-mark-(\d+)/m)[1])];if("object"==typeof n&&"unsafeHTML"===n.type){let e=document.createElement("div");for(e.innerHTML=n.value;e.firstChild;)t.parentNode?.insertBefore(e.firstChild,t);t.remove()}else t.replaceWith(document.createTextNode(String(n)))}})(),(()=>{let t,r=document.createTreeWalker(n.content,NodeFilter.SHOW_ELEMENT);for(;t=r.nextNode();)for(const n of Array.from(t.attributes))if(/<!--si-mark-\d+-->/gm.test(n.value)){const r=n.value.match(/si-mark-(\d+)/m);if(r){const o=e.values[Number(r[1])];t.setAttribute(n.name,String(o))}}})(),n}templateToElement(e,t){const n=this.templateToString(e),r=this.fillTemplate(e,n);if(1!==r.content.children.length)throw{id:"multiple-root-elements",elements:r.innerHTML,component:t};return r.content.firstElementChild}render(t){for(const r of Object.keys(this.components)){const o=this.components[r];for(const s of Array.from(t.querySelectorAll(r)).concat(Array.from(t.querySelectorAll(`[si-component="${r}"]`)))){const t=new o;if(t.$=this.$g,Object.freeze(t.$),t.onInit?.(),s instanceof HTMLElement){t.content=s.innerHTML.trim();for(const e of Object.keys(t.props)){const n=s.getAttribute(e);if(null===n){if(t.props[e].required)throw{id:"prop-is-required",component:r,prop:e};t.data[e]=null}else if(""===n){if(t.props[e].required)throw{id:"prop-is-required",component:r,prop:e};t.props[e].isValid(n)&&(t.data[e]=null)}else{let o;switch(t.props[e].type){case"boolean":o=Boolean(n);break;case"number":o=Number(n);break;case"string":o=String(n);break;case"array":try{o=JSON.parse(n)}catch(t){throw{id:"invalid-value-for-property",component:r,prop:e,value:n,attr:n}}break;default:if(t.props[e].required)throw{id:"unsupported-type-for-property",component:r,prop:e,type:t.props[e].type}}if(void 0!==o){if(!t.props[e].isValid(o))throw{id:"invalid-value-for-property",component:r,prop:e,value:o,attr:n};if(t.props[e].validate&&!t.props[e].validate(o))throw{id:"invalid-value-for-property",component:r,prop:e,value:o,attr:n};t.data[e]=o,t.onPropParsed?.(t.props[e],o)}}}t.onPropsParsed?.()}const i=document.createElement("template");let a={strings:Object.assign([],{raw:[]}),values:[]};try{a=t.render()}catch(e){if(e instanceof Error)throw{id:"unknown-from",from:t.name,err:e}}(e=>{if(a instanceof Promise)try{a.then(t=>{i.appendChild(this.templateToElement(t,r)),e()}).catch(e=>{throw{id:"unknown-from",from:t.name,err:e}})}catch(e){throw{id:"render-async-failed",component:r,err:e}}else"object"==typeof a&&(i.appendChild(this.templateToElement(a,r)),e())})(()=>{this.render(i.content),t.onRender?.();const o=i.firstElementChild;if(t?.groups.length>0&&o.setAttribute("si-group",t.groups.join(" ")),s.hasAttribute("ref")\|\|t.options.generateRefIfNotSpecified){let i=s.getAttribute("ref");if(null===i&&(i=""),n++,""===i&&(i=`r${n}${Math.random().toString(36).substring(2,15)}${n}`),this.refs[i])throw{id:"ref-collision",ref:i,component:r};this.refs[i]=new e(t,o),o.setAttribute("ref",i),t.ref={id:i,contact:(...e)=>this.contactWith(i,...e),update:()=>this.updateRef(i)}}for(const e of Array.from(s.attributes)){const n=e.name;void 0===t.props[n]&&"ref"!==n&&"si-component"!==n&&"si-group"!==n&&(o.hasAttribute(n)\|\|o.setAttribute(n,e.value))}s.replaceWith(i.firstElementChild),t.onMount?.(o)})}}}}class o{content;groups=[];options={generateRefIfNotSpecified:!1};ref;props={};data={};$={};onInit(){}onRender(){}onMount(e){}onContact(...e){}onPropsParsed(){}onPropParsed(e,t){}}class s{type;required=!0;validate;constructor(e,t=!0,n){this.type=e,this.required=t,this.validate=n\|\|(()=>!0)}isValid(e){switch(this.type){case"boolean":return"boolean"==typeof e;case"number":return"number"==typeof e&&!isNaN(e);case"string":return"string"==typeof e;case"array":return Array.isArray(e);case"null":return null===e;default:return!1}}}class i{name;version;author;libs={};components={};constructor(e,t,n){this.name=e,this.author=t,this.version=n}add(e,t){const n="string"==typeof t?t:e.name;this.components[n]&&console.warn(new Error(`Component with name ${n} already exists.`)),this.components[n]=e}register(e,...t){this.libs[e.name]&&console.warn(new Error(`Library with name ${e.name} already exists in ${this.name}.`));const n=e.list().filter(e=>!(e.name in t));this.libs[e.name]={name:e.name,version:e.version,author:e.author,components:n.map(e=>e.name),dependencies:e.libs};for(const t of n)this.add(t.component,`${e.name}-${t.name}`)}get(e){return this.components[e]}lib(e){return this.libs[e]}list(){return Object.entries(this.components).map(([e,t])=>({component:t,name:e}))}}function a(e,...t){return{strings:e,values:t}}function c(e){return{type:"unsafeHTML",value:e}}class l{}function p(){return new r}export{o as Component,i as Library,l as Plugin,s as Prop,r as Signature,p as default,a as html,c as unsafeHTML};

package/dist/Component.js CHANGED Viewed

@@ -1,11 +1,13 @@
 export default class Component {
     content;
+    groups = [];
     options = {
         generateRefIfNotSpecified: false,
     };
     ref;
     props = {};
     data = {};
+    $ = {};
     onInit() {
     }
     ;

package/dist/Plugin.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export default class Plugin {
2	+ }

package/dist/Signature.js CHANGED Viewed

@@ -6,6 +6,8 @@ export default class Signature {
     refs = {};
     libs = {};
     bank = new Map();
+    $ = {};
+    $g = {};
     constructor() {
     }
     /**
@@ -79,6 +81,26 @@ export default class Signature {
         };
         return resolve(this.libs);
     }
+    /**
+     * Registers a plugin in the signature.
+     * @import {Plugin} from "./Plugin.js";
+     * @param {string} name The name of the plugin.
+     * @param {Plugin} plugin The plugin to register.
+     */
+    use(name, plugin) {
+        if (this.$[name]) {
+            throw new Error(`Plugin with name ${name} already exists.`);
+        }
+        let modules = {};
+        Object.keys(plugin.modules).forEach((key) => {
+            modules[key] = plugin.modules[key]();
+        });
+        this.$[name] = {
+            plugin: plugin.define(modules),
+            modules
+        };
+        this.$g[name] = this.$[name].plugin;
+    }
     /**
      * Contacts the Component.onContact method through its reference.
      * @param {string} name The name of the reference.
@@ -133,6 +155,15 @@ export default class Signature {
                 throw new Error(`Component '${component.name}' must render a single root element.`);
             }
             const newElement = template.content.firstElementChild;
+            // Preserve old ref attribute
+            let oldRef = ref.element.getAttribute("ref");
+            if (oldRef) {
+                newElement.setAttribute("ref", oldRef);
+            }
+            // Preserve si-group attribute
+            if (component.groups.length > 0) {
+                newElement.setAttribute("si-group", component.groups.join(" "));
+            }
             this.render(template.content);
             component.onRender?.(); // lifecycle hook
             ref.element.replaceWith(newElement);
@@ -266,6 +297,8 @@ export default class Signature {
             // Find all elements with the component name in the frame
             for (const el of Array.from(frame.querySelectorAll(com)).concat(Array.from(frame.querySelectorAll(`[si-component="${com}"]`)))) {
                 const renderer = new component();
+                renderer.$ = this.$g; // injecting plugins
+                Object.freeze(renderer.$); // prevent plugins from being modified by components
                 renderer.onInit?.(); // lifecycle hook
                 if (el instanceof HTMLElement) {
                     // Fill the renderer's content
@@ -391,6 +424,10 @@ export default class Signature {
                     this.render(body.content);
                     renderer.onRender?.(); // lifecycle hook
                     const mountEl = body.firstElementChild;
+                    // Processing group
+                    if (renderer?.groups.length > 0) {
+                        mountEl.setAttribute("si-group", renderer.groups.join(" "));
+                    }
                     // Processing ref
                     if (el.hasAttribute("ref") || renderer.options.generateRefIfNotSpecified) {
                         let refName = el.getAttribute("ref");
@@ -413,6 +450,14 @@ export default class Signature {
                             update: () => this.updateRef(refName)
                         };
                     }
+                    // Copying another attributes from the original element to the new one, with exceptions
+                    for (const attr of Array.from(el.attributes)) {
+                        const name = attr.name;
+                        if (renderer.props[name] !== undefined || name === "ref" || name === "si-component" || name === "si-group")
+                            continue;
+                        if (!mountEl.hasAttribute(name))
+                            mountEl.setAttribute(name, attr.value);
+                    }
                     el.replaceWith(body.firstElementChild);
                     renderer.onMount?.(mountEl); // lifecycle hook
                 });

package/dist/d/Component.d.ts CHANGED Viewed

@@ -5,10 +5,12 @@ import type { Ref } from "./types/Component.js";
 export default abstract class Component implements component {
     abstract readonly name: string;
     content?: string;
+    groups: string[];
     options: Options;
     ref?: Ref;
     readonly props: Record<string, Prop>;
     readonly data: Record<string, string | number | boolean | null>;
+    $: Record<string, unknown>;
     abstract render(): html | Promise<html>;
     onInit?(): void;
     onRender?(): void;

package/dist/d/Plugin.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+export default abstract class Plugin {
+    /**
+     * Modules are mini plugins that are required for the plugin to work, they are processed and stored before the plugin itself is installed and stored in a safe place.
+     */
+    readonly abstract modules: Record<string, () => Record<string, unknown>>;
+    /**
+     * The function returns an object that will be installed as a plugin in Signature.$
+     * @param modules
+     * @returns {Record<string, unknown>} The object that will be installed as a plugin
+     */
+    abstract define(modules: Record<string, Record<string, unknown>>): Record<string, unknown>;
+}

package/dist/d/Signature.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import { ComponentConstructor } from "./Component.js";
 import Library, { LibMeta } from "./Library.js";
+import Plugin from "./Plugin.js";
 type ResolvedLib = {
     components: string[];
     dependencies: Record<string, ResolvedLib>;
@@ -9,6 +10,8 @@ export default class Signature {
     private refs;
     private libs;
     private bank;
+    private $;
+    private $g;
     constructor();
     /**
      * Adds a component to the signature.
@@ -34,6 +37,13 @@ export default class Signature {
      * @return {Record<string, ResolvedLib>} A object of formatted libraries with their components and dependencies.
      */
     libraries(): Record<string, ResolvedLib>;
+    /**
+     * Registers a plugin in the signature.
+     * @import {Plugin} from "./Plugin.js";
+     * @param {string} name The name of the plugin.
+     * @param {Plugin} plugin The plugin to register.
+     */
+    use(name: string, plugin: Plugin): void;
     /**
      * Contacts the Component.onContact method through its reference.
      * @param {string} name The name of the reference.

package/dist/d/html.d.ts CHANGED Viewed

@@ -1,8 +1,12 @@
-export default function html(strings: TemplateStringsArray, ...values: any[]): {
+type HTMLTemplate = {
     strings: TemplateStringsArray;
     values: any[];
 };
-export declare function unsafeHTML(value: any): {
+export default function html(strings: TemplateStringsArray, ...values: any[]): HTMLTemplate;
+type unsafeHTMLTemplate = {
     type: "unsafeHTML";
     value: any;
 };
+export declare function unsafeHTML(value: any): unsafeHTMLTemplate;
+export declare function joinTemplates(...templates: HTMLTemplate[]): HTMLTemplate;
+export {};

package/dist/d/index.d.ts CHANGED Viewed

@@ -5,3 +5,4 @@ export { default as Component } from './Component.js';
 export { default as Prop } from './Prop.js';
 export { default as Library } from './Library.js';
 export { default as html, unsafeHTML } from './html.js';
+export { default as Plugin } from './Plugin.js';

package/dist/d/types/Component.d.ts CHANGED Viewed

@@ -37,6 +37,10 @@ interface Component {
      * Optional content that is specified in the component tag.
      */
     content?: string;
+    /**
+     * Optional groups that the component belongs to.
+     */
+    groups: string[];
     /**
      * Defining component properties.
      */
@@ -45,6 +49,10 @@ interface Component {
      * The properties of the component.
      */
     data: Record<string, string | number | boolean | null>;
+    /**
+     * Plugins are stored here.
+     */
+    $: Record<string, unknown>;
     /**
      * Returns the component as a string (template).
      * @returns {html | Promise<html>} The rendered component as a string (template).

package/dist/d/types/MetaPlugin.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+interface MetaPlugin {
+    plugin: Record<string, unknown>;
+    modules: Record<string, Record<string, unknown>>;
+}
+export type { MetaPlugin as default };

package/dist/html.js CHANGED Viewed

@@ -4,3 +4,16 @@ export default function html(strings, ...values) {
 export function unsafeHTML(value) {
     return { type: "unsafeHTML", value: value };
 }
+export function joinTemplates(...templates) {
+    let strings = [];
+    let values = [];
+    templates.forEach((t) => {
+        strings.push(...t.strings);
+        values.push(...t.values);
+    });
+    return {
+        strings: strings,
+        values: values
+    };
+}
+// todo: make a loop function

package/dist/index.js CHANGED Viewed

@@ -7,3 +7,4 @@ export { default as Component } from './Component.js';
 export { default as Prop } from './Prop.js';
 export { default as Library } from './Library.js';
 export { default as html, unsafeHTML } from './html.js';
+export { default as Plugin } from './Plugin.js';

package/dist/types/MetaPlugin.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "web-signature",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "description": "Primitive and fast framework for rendering web interfaces",
   "license": "ISC",
   "author": "PinBib",

package/src/Component.ts CHANGED Viewed

@@ -8,6 +8,8 @@ export default abstract class Component implements component {
 	abstract readonly name: string;
 	content?: string;
+	groups: string[] = [];
 	options: Options = {
 		generateRefIfNotSpecified: false,
 	}
@@ -17,6 +19,8 @@ export default abstract class Component implements component {
 	readonly props: Record<string, Prop> = {};
 	readonly data: Record<string, string | number | boolean | null> = {};
+	public $: Record<string, unknown> = {};
 	abstract render(): html | Promise<html>;
 	onInit?(): void {

package/src/Plugin.ts ADDED Viewed

@@ -0,0 +1,13 @@
+export default abstract class Plugin {
+	/**
+	 * Modules are mini plugins that are required for the plugin to work, they are processed and stored before the plugin itself is installed and stored in a safe place.
+	 */
+	readonly abstract modules: Record<string, () => Record<string, unknown>>;
+	/**
+	 * The function returns an object that will be installed as a plugin in Signature.$
+	 * @param modules
+	 * @returns {Record<string, unknown>} The object that will be installed as a plugin
+	 */
+	public abstract define(modules: Record<string, Record<string, unknown>>): Record<string, unknown>;
+}

package/src/Signature.ts CHANGED Viewed

@@ -3,7 +3,9 @@ import Ref from "./Ref.js";
 import ErrorUnion from "./types/Errors.js";
 import Errors from "./Errors.js";
 import Library, {LibMeta} from "./Library.js";
-import {html} from "./types/Component";
+import {html} from "./types/Component.js";
+import MetaPlugin from "./types/MetaPlugin.js";
+import Plugin from "./Plugin.js";
 let _counter = 0;
@@ -16,7 +18,10 @@ export default class Signature {
 	private components: Record<string, ComponentConstructor> = {};
 	private refs: Record<string, Ref> = {};
 	private libs: Record<string, LibMeta> = {};
-	private bank: Map<string, HTMLTemplateElement> = new Map<string, HTMLTemplateElement>()
+	private bank: Map<string, HTMLTemplateElement> = new Map<string, HTMLTemplateElement>();
+	private $: Record<string, MetaPlugin> = {};
+	private $g: Record<string, unknown> = {};
 	constructor() {
 	}
@@ -109,6 +114,31 @@ export default class Signature {
 		return resolve(this.libs);
 	}
+	/**
+	 * Registers a plugin in the signature.
+	 * @import {Plugin} from "./Plugin.js";
+	 * @param {string} name The name of the plugin.
+	 * @param {Plugin} plugin The plugin to register.
+	 */
+	public use(name: string, plugin: Plugin): void {
+		if (this.$[name]) {
+			throw new Error(`Plugin with name ${name} already exists.`);
+		}
+		let modules: Record<string, Record<string, unknown>> = {};
+		Object.keys(plugin.modules).forEach((key) => {
+			modules[key] = plugin.modules[key]();
+		});
+		this.$[name] = {
+			plugin: plugin.define(modules),
+			modules
+		};
+		this.$g[name] = this.$[name].plugin;
+	}
 	/**
 	 * Contacts the Component.onContact method through its reference.
 	 * @param {string} name The name of the reference.
@@ -172,6 +202,17 @@ export default class Signature {
 			const newElement = template.content.firstElementChild as Element;
+			// Preserve old ref attribute
+			let oldRef = ref.element.getAttribute("ref");
+			if (oldRef) {
+				newElement.setAttribute("ref", oldRef);
+			}
+			// Preserve si-group attribute
+			if (component.groups.length > 0) {
+				newElement.setAttribute("si-group", component.groups.join(" "));
+			}
 			this.render(template.content);
 			component.onRender?.(); // lifecycle hook
@@ -341,6 +382,10 @@ export default class Signature {
 			// Find all elements with the component name in the frame
 			for (const el of Array.from(frame.querySelectorAll(com)).concat(Array.from(frame.querySelectorAll(`[si-component="${com}"]`)))) {
 				const renderer: Component = new component();
+				renderer.$ = this.$g; // injecting plugins
+				Object.freeze(renderer.$); // prevent plugins from being modified by components
 				renderer.onInit?.(); // lifecycle hook
 				if (el instanceof HTMLElement) {
@@ -476,6 +521,11 @@ export default class Signature {
 					const mountEl: Element = body.firstElementChild as Element;
+					// Processing group
+					if (renderer?.groups.length > 0) {
+						mountEl.setAttribute("si-group", renderer.groups.join(" "));
+					}
 					// Processing ref
 					if (el.hasAttribute("ref") || renderer.options.generateRefIfNotSpecified) {
 						let refName = el.getAttribute("ref");
@@ -506,6 +556,15 @@ export default class Signature {
 						};
 					}
+					// Copying another attributes from the original element to the new one, with exceptions
+					for (const attr of Array.from(el.attributes)) {
+						const name: string = attr.name;
+						if (renderer.props[name] !== undefined || name === "ref" || name === "si-component" || name === "si-group") continue;
+						if (!mountEl.hasAttribute(name)) mountEl.setAttribute(name, attr.value);
+					}
 					el.replaceWith(body.firstElementChild as Element);
 					renderer.onMount?.(mountEl); // lifecycle hook

package/src/html.ts CHANGED Viewed

@@ -1,10 +1,31 @@
-export default function html(strings: TemplateStringsArray, ...values: any[]): {
+type HTMLTemplate = {
 	strings: TemplateStringsArray,
 	values: any[]
-} {
+};
+export default function html(strings: TemplateStringsArray, ...values: any[]): HTMLTemplate {
 	return {strings, values};
 }
-export function unsafeHTML(value: any): { type: "unsafeHTML", value: any } {
+type unsafeHTMLTemplate = { type: "unsafeHTML", value: any };
+export function unsafeHTML(value: any): unsafeHTMLTemplate {
 	return {type: "unsafeHTML", value: value};
-}
+}
+export function joinTemplates(...templates: HTMLTemplate[]): HTMLTemplate {
+	let strings: string[] = [];
+	let values: any[] = [];
+	templates.forEach((t) => {
+		strings.push(...t.strings);
+		values.push(...t.values);
+	});
+	return {
+		strings: strings as unknown as TemplateStringsArray,
+		values: values
+	} as HTMLTemplate;
+}
+// todo: make a loop function

package/src/index.ts CHANGED Viewed

@@ -8,4 +8,5 @@ export {default as Signature} from './Signature.js';
 export {default as Component} from './Component.js';
 export {default as Prop} from './Prop.js';
 export {default as Library} from './Library.js';
-export {default as html, unsafeHTML} from './html.js';
+export {default as html, unsafeHTML} from './html.js';
+export {default as Plugin} from './Plugin.js';

package/src/types/Component.ts CHANGED Viewed

@@ -47,6 +47,11 @@ interface Component {
 	 */
 	content?: string;
+	/**
+	 * Optional groups that the component belongs to.
+	 */
+	groups: string[];
 	/**
 	 * Defining component properties.
 	 */
@@ -57,6 +62,10 @@ interface Component {
 	 */
 	data: Record<string, string | number | boolean | null>;
+	/**
+	 * Plugins are stored here.
+	 */
+	$: Record<string, unknown>;
 	/**
 	 * Returns the component as a string (template).

package/src/types/MetaPlugin.ts ADDED Viewed

@@ -0,0 +1,6 @@
+interface MetaPlugin {
+	plugin: Record<string, unknown>;
+	modules: Record<string, Record<string, unknown>>;
+}
+export type {MetaPlugin as default};