@twobirds/microcomponents
Version:
Micro Components Organization Class
76 lines (72 loc) • 20.3 kB
HTML
<html class="default" lang="en"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Micro Components</title><meta name="description" content="Documentation for Micro Components"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">Micro Components</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>Micro Components</h1></div><div class="tsd-panel tsd-typography"><p><img src="media/MicroComponents.svg" alt="logo"></p>
<a id="md:micro-components" class="tsd-anchor"></a><h2 class="tsd-anchor-link">MICRO COMPONENTS<a href="#md:micro-components" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><strong>This code aims at improving Javascript modularity and encapsulation</strong>.</p>
<p>Micro Components are built on <strong>OOP</strong> for structure, so you should embrace <strong>DRY, KISS and SOLID</strong> principles. That said, OOP is not a religion here, in fact you can do FP also. MCs provide a structure for your code, no more. It is agnostic as to what code you put in this structure.</p>
<p>Its basic principle is <strong>composition over inheritance</strong>. So: using OOP its recommended you do not extend your own classes, as it is not needed.</p>
<p>Also it helps to embrace <strong>DIY</strong> (Do It Yourself) <strong>over Toolchains</strong>, but this is up to your personal preference.</p>
<p>You can use <strong>Vanilla JS or Typescript</strong> or both in your project. For example you could use plain JS for rapid prototyping functionalities, then convert to TS for production.</p>
<a id="md:think-building-blocks" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Think <strong>Building Blocks</strong><a href="#md:think-building-blocks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>In general this is a <strong>HTML / Web Standards first</strong> system. There is almost no abstraction, especially not for templating, except state binding to the DOM via simple placeholders.</p>
<p>When coding with this system, you create classes that extend either the <strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads#mc-class-extends-mcbase" target="_blank" class="external">MC</a></strong> or <strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads#dc-class-extends-mcbase" target="_blank" class="external">DC</a></strong> superclasses provided here. These classes provide the structure you need to build your wonderland.</p>
<p>You <strong>attach instances of your classes to any HTMLElement</strong>, and there can be as many as you want connected to a single HTML tag. In an almost literal sense they work like childrens building blocks, where a chest full of unassuming parts lets you compose whatever functionality lies in your imagination.</p>
<p>Also you can easily <strong>define JS custom elements</strong>. Since these are just another instance of a DC internally, you can enhance them even at runtime, as they are displayed in the browser.</p>
<a id="md:principles" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Principles<a href="#md:principles" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This systems <strong>modular</strong> approach gives you full control over your software, without the need to rely on other frameworks.</p>
<p>On the other hand, its <strong>minimalistic</strong> stance enables you to use the resulting functionality in any other framework, and makes the <strong>learning curve neglectable</strong>.</p>
<a id="md:status" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Status<a href="#md:status" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>In <a href="https://twobirds.gitlab.io/microcomponents/test/test.html" target="_blank" class="external">manual testing</a> ( also a speed test). I am working on the documentation.</p>
<a id="md:general" class="tsd-anchor"></a><h2 class="tsd-anchor-link">General<a href="#md:general" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This repository exports 4 independent functionalities:</p>
<ol>
<li>
<p><strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads" target="_blank" class="external">Micro Components</a></strong> contains the <strong>MC</strong> and <strong>DC</strong> classes you can use as super classes.</p>
</li>
<li>
<p><strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/elements.md?ref_type=heads" target="_blank" class="external">Elements</a></strong> lets you define and use your own native web components. Uses (1).</p>
</li>
</ol>
<ul>
<li><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/elements.md?ref_type=heads#create-a-custom-element" target="_blank" class="external">Basic Usage</a>.</li>
<li><a href="https://twobirds.gitlab.io/microcomponents/test/test.html" target="_blank" class="external">Live Example</a></li>
</ul>
<ol start="3">
<li><strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/observables.md?ref_type=heads" target="_blank" class="external">Observables</a></strong> add <strong>observability</strong> and <strong>run time type safety</strong> to object properties. Also they provide <strong>1-way binding</strong> to placeholders in your template HTML.</li>
</ol>
<ul>
<li><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/observables.md?ref_type=heads#example" target="_blank" class="external">Basic Usage</a></li>
<li><a href="https://twobirds.gitlab.io/microcomponents/test/test.html" target="_blank" class="external">Live Example</a></li>
</ul>
<ol start="4">
<li><strong><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/formvalues.md?ref_type=heads" target="_blank" class="external">Formvalues</a></strong> gives you <strong>2-way binding</strong> between a HTML form and an observable object. Uses (3).</li>
</ol>
<ul>
<li><a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/src/test/test/testform.ts?ref_type=heads" target="_blank" class="external">Example Code</a></li>
<li><a href="https://twobirds.gitlab.io/microcomponents/test/test.html" target="_blank" class="external">Live Example</a></li>
</ul>
<p>Also there is a bundle file that contains all of the above.</p>
<p>Check the <a href="https://twobirds.gitlab.io/microcomponents/typedoc/index.html" target="_blank" class="external">typedoc API reference</a> if you want to drill into the source code.</p>
<p>To see what can be done, go to <a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/magic.md?ref_type=heads" target="_blank" class="external">additional concepts</a> which shows what it already has been used for.</p>
<a id="md:simple-usage-example" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Simple Usage Example<a href="#md:simple-usage-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><strong>Micro Components</strong> can be added to to a DOM element like this:</p>
<p>before:</p>
<pre><code class="HTML"><span class="hl-0"><</span><span class="hl-1">div</span><span class="hl-0">></</span><span class="hl-1">div</span><span class="hl-0">></span>
</code><button type="button">Copy</button></pre>
<p>code:</p>
<pre><code class="typescript"><span class="hl-2">// create a custom micro component class</span><br/><span class="hl-3">class</span><span class="hl-4"> </span><span class="hl-5">MyMC</span><span class="hl-4"> </span><span class="hl-3">extends</span><span class="hl-4"> </span><span class="hl-5">DC</span><span class="hl-4">{</span><br/><br/><span class="hl-4"> </span><span class="hl-3">constructor</span><span class="hl-4">( </span><span class="hl-6">target</span><span class="hl-4"> ){</span><br/><span class="hl-4"> </span><span class="hl-3">super</span><span class="hl-4">( </span><span class="hl-6">target</span><span class="hl-4"> );</span><br/><span class="hl-4"> }</span><br/><br/><span class="hl-4"> </span><span class="hl-7">helloWorld</span><span class="hl-4">(){</span><br/><span class="hl-4"> </span><span class="hl-6">console</span><span class="hl-4">.</span><span class="hl-7">log</span><span class="hl-4">( </span><span class="hl-8">'Hello World'</span><span class="hl-4"> );</span><br/><span class="hl-4"> }</span><br/><br/><span class="hl-4">}</span><br/><br/><span class="hl-2">// get some element from the DOM</span><br/><span class="hl-3">const</span><span class="hl-4"> </span><span class="hl-9">element</span><span class="hl-4"> = </span><span class="hl-6">document</span><span class="hl-4">.</span><span class="hl-7">querySelector</span><span class="hl-4">(</span><span class="hl-8">'div'</span><span class="hl-4">)</span><br/><br/><span class="hl-2">// Add the custom micro component instance to the target element</span><br/><span class="hl-9">DC</span><span class="hl-4">.</span><span class="hl-7">add</span><span class="hl-4">(</span><br/><span class="hl-4"> </span><span class="hl-6">element</span><span class="hl-4">,</span><br/><span class="hl-4"> </span><span class="hl-8">'myMC'</span><span class="hl-4">,</span><br/><span class="hl-4"> </span><span class="hl-3">new</span><span class="hl-4"> </span><span class="hl-7">MyMC</span><span class="hl-4">( </span><span class="hl-6">element</span><span class="hl-4"> )</span><br/><span class="hl-4">);</span><br/><br/><span class="hl-2">// Hello World</span><br/><span class="hl-6">element</span><br/><span class="hl-4"> .</span><span class="hl-6">_mc</span><br/><span class="hl-4"> .</span><span class="hl-6">myMC</span><br/><span class="hl-4"> .</span><span class="hl-7">helloWorld</span><span class="hl-4">();</span>
</code><button type="button">Copy</button></pre>
<p>after:</p>
<pre><code class="HTML"><span class="hl-0"><</span><span class="hl-1">div</span><span class="hl-4"> </span><span class="hl-10">_mc</span><span class="hl-0">></</span><span class="hl-1">div</span><span class="hl-0">></span>
</code><button type="button">Copy</button></pre>
<p>The <code>_mc</code> <strong>attribute</strong> indicates that this <strong>HTML element contains at least one micro component</strong>. This is needed for the selectors.</p>
<p>The <code>_mc</code> <strong>attribute</strong> and <strong>property</strong> are the only interference with the DOM, so any other system should be happy to work with this.</p>
<a id="md:distinct-differences-to-other-frameworks" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Distinct differences to other frameworks<a href="#md:distinct-differences-to-other-frameworks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>There are a few potentially unique aspects of this micro components system that might differentiate it from other frameworks:</p>
<ul>
<li><strong>Pure OOP Approach</strong>: The system explicitly positions itself as a strict object-oriented alternative to the functional approaches that dominate many modern frameworks.</li>
<li><strong>Minimal Interference</strong>: The system has minimal DOM interference (only adding _mc attribute and property). This makes it unusually compatible with other frameworks or libraries.</li>
<li><strong>Hierarchical Component Traversal</strong>: The built-in parent/child/ancestor/descendant traversal methods provide a clean way to navigate component relationships.</li>
<li><strong>Direct DOM Integration</strong>: Unlike virtual DOM-based frameworks, this approach works directly with the actual DOM while still providing component encapsulation.</li>
<li><strong>Outsourcing Potential</strong>: Your external coders do not need to access your code repository or your toolchain.</li>
</ul>
<p>The strongest argument might be for developers who prefer OOP, want minimal framework lock-in, and need a lightweight solution that works well with existing code or other libraries.</p>
<a id="md:contact" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Contact<a href="#md:contact" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Feel free to contact me for any questions or inquiries:</p>
<p>email <a href="mailto:fthuerigen@gmail.com?subject=Micro%20Components">Frank Thürigen</a></p>
<p>You can <a href="https://www.gofundme.com/f/nachhaltige-programmierung" target="_blank" class="external">fund this</a>.</p>
<a id="md:disclaimer" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Disclaimer<a href="#md:disclaimer" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>I decided to extract this functionality from the <a href="https://www.npmjs.com/package/twobirds-core" target="_blank" class="external">twoBirds framework</a>, because it is a useful tool in itself and it is framework agnostic. It relies solely on the standard DOM and native javascript or typescript.</p>
<p>Later this will be backported into twoBirds as a dependency, and twoBirds will become completely modularized on the base of MCs.</p>
<p><strong>This is a massive undertaking.</strong> MCs are just the foundation of what I do. I am about to dump <a href="https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/magic.md?ref_type=heads#things-i-already-did-with-this-in-my-own-framework-twobirds-or-in-apps-that-i-developed-with-it" target="_blank" class="external">20+ years of javascript programming</a> into open source libraries, so feel free to <a href="https://www.gofundme.com/f/nachhaltige-programmierung" target="_blank" class="external">fund this</a>. The better this is funded, the faster it will be done. Given enough resources, I will start a crowdfunded company that will develop a new open source ecosystem for javascript/typescript programming. By <strong>"Open Source"</strong> I mean <strong>really free and open</strong>, as <strong>you get all my inner source code with it</strong>. Once you understand the Micro Component principle, you are back in command of your software, no matter what MC functionality you import in your system.</p>
<p>Since <strong>Micro Components</strong> are encapsuled, off-shoring and near-shoring is no problem, and reusability is guaranteed. Your external coders do not need to access your code repository or your toolchain. They only need to understand MCs.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#md:micro-components"><span>MICRO COMPONENTS</span></a><a href="#md:think-building-blocks"><span>Think <wbr/>Building <wbr/>Blocks</span></a><a href="#md:principles"><span>Principles</span></a><a href="#md:status"><span>Status</span></a><a href="#md:general"><span>General</span></a><a href="#md:simple-usage-example"><span>Simple <wbr/>Usage <wbr/>Example</span></a><a href="#md:distinct-differences-to-other-frameworks"><span>Distinct differences to other frameworks</span></a><a href="#md:contact"><span>Contact</span></a><a href="#md:disclaimer"><span>Disclaimer</span></a></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current"><svg class="tsd-kind-icon" viewBox="0 0 24 24"><use href="assets/icons.svg#icon-1"></use></svg><span>Micro Components</span></a><ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base="."><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>