@twobirds/microcomponents 0.0.12 → 0.0.15

package/public/documentation/magic.md

@@ -0,0 +1,87 @@
+# Additional concepts: how to make the magic happen...
+
+**Micro Components** can literally be anything you can put into an object as a property.
+
+Here are some examples of what **Micro Components** can really archieve.
+
+
+## The MC() class can be used as a selector of its own, even if you dont attach a micro component yourself
+
+Since MC is a class you instanciate with a target element as your selection root element, and you can do this:
+
+```javascript
+const myElement = document.getElementById('myDiv');
+
+// find the nearst MC parent elements to this HTMLElement
+const myParent = ( new MC( myElement ) ).parent();
+```
+
+## Since MC() is a class, you can extend your own micro components with it and have the selectors nicely available
+
+Here is some typical usage:
+
+```javascript
+class MyMicroComponent extends MC {
+
+	constructor( target ){
+		super(target);
+	}
+
+	showParents(){
+		console.log( this.parents() ); // Logs all anchestor micro components
+	}
+}
+
+let myDiv = document.querySelector('div');
+
+MC.add( myDiv, 'my_micro_component', new MyMicroComponent( myDiv ) );
+
+// TADA!
+myDiv
+	._mc
+	.my_micro_component
+	.showParents();
+```
+
+As you can see, without any effort you have a **second structural layer that hovers over the DOM**.
+
+The browser knows nothing of this, except that there may be _mc properties on some HTMLElements.
+
+It doesnt get more standard compliant than that.
+
+
+## Things I already did with this, in my own framework twoBirds, or in apps that I developed with it:
+
+- `encapsulated and modular 3D rendering` in an HTMLElement viewport.
+- `Data Driven Workflow` with micro components using tB specific observables.
+- `DOM handling` in general, lots of `UI functionality`
+- `2 way Data Binding` between forms and observable objects representing the form data
+- `1 way Data Binding` from data observables to the DOM
+- `Loose Coupling` via my own event objects
+- `Rule Engines`
+- `Complex Runtime Templating` without JSX or virtual DOM
+- `Single Page Applications`
+- `Micro Frontends`
+- `Electron Apps`
+- `Progressive Web Apps`
+- `Complex Native Web Components`, that comprised of a set of modular `UI` and `business logic` micro components
+- this ran on the `server` also, in standalone linux nodeJs processes. I removed this some time ago because I didnt want server and client code in one library. Now its easy to make a server variant of the micro component code if required.
+
+
+Funny stuff:
+
+- `Vending Machine Frontends`
+- some `Simulators`
+- `UI for ocean going container ships`
+
+
+Not from me, but somehow based on my ideas:
+
+- `SpaceX` uses web components as an interface in their `Dragon Capsule`. I kind of regard myself to be a co-inventor of web components, since I announced my idea on ajaxian.com in 2007. Anyway, much later the [User defined built in elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#customized_built-in_elements) were a copy of what I already had then. So in a way, this already goes to space.
+
+
+
+This list is far from complete, I used this as a core principle for 20 years. All of the above is modular, so you can use it together.
+
+
+**Whatever functionality you can do with Javascript, you can encapsule it in a micro component and reuse in any framework that allows for DOM access**.

package/public/documentation/proposal_draft.md

@@ -0,0 +1,37 @@
+### RFC Proposal to WHATWG
+
+**Title:** Proposal for a **Micro Component Interface** in the DOM
+
+**Abstract:**
+
+This proposal introduces a standardized interface for managing micro components within HTML elements, enhancing modularity and reusability in web development.
+
+**Introduction:**
+
+Microcomponents provide a way to encapsulate functionality and state within a target DOM element. This proposal outlines methods for adding, removing, and querying micro components.
+
+**Proposed API:**
+
+- **Static Methods:**
+  - `MC.add( target, key, element)`: Attach a top level micro component to an HTMLElement.
+  - `MC.remove( target, key )`: Detach a top level micro component from an HTMLElement.
+  - `MC.siblings( target )`: get top level micro components from an HTMLElement.
+
+- **Instance Methods:**
+  - `add( key, element )`: Attach a private Micro Component to a Micro Component.
+  - `remove( key )`: Detach a private Micro Component from a Micro Component.
+  - `siblings(search?)`: Retrieve sibling micro components.
+  - `parent(search?)`: Get parent top level micro components.
+  - `parents(search?)`: Get all ancestor top level micro components.
+  - `children(search?)`: Retrieve child top level micro components.
+  - `descendants(search?)`: Get all descendant top level micro components.
+
+**Use Cases:**
+1. Modular web applications.
+2. Enhancing component-based architecture.
+
+**Conclusion:**
+Implementing this interface will streamline microcomponent management, fostering cleaner code and improved performance.
+
+**References:**
+- [Microcomponents Repository](https://gitlab.com/twoBirds/microcomponents) for a polyfill implementation and usage examples.

package/public/documentation/tB_react.md

@@ -0,0 +1,233 @@
+# Discussing React Prop Drilling with ChatGPT
+
+This is an interesting read where I wanted ChatGPT to come up with a Micro Component solution for a React problem.
+
+To be honest, I knew MCs can solve it. But I wanted to know what ChatGPT can make of it. Spoiler: it got remarkably close on the first try. The second try was spot on.
+
+Please mind I have a trained session with a backlog. So you wont get the same answers.
+
+***( Cut outs and comments are in parentheses...)***
+
+
+## Disclaimer:
+
+The answers partly reflect on the twoBirds framework instead of Micro Components. twoBirds converts all props into convenience observables automatically, which MCs don't do.
+
+The code ChatGPT generated first isn't quite right therefore. Also since I am not a react specialist I cannot guarantee for that part. In general, this is close enough though.
+
+I edited the code to reflect the right solution and annotated my changes.
+
+I put that into the first answer and asked ChatGPT again.
+
+The second answer was spot on, assuming some magic for the convenience observables.
+
+Bonus: during this process I got the inspiration that there should be several kinds of state objects:
+
+- readonlyState: exports some inner props to the DOM for others to read, but the external state cannot be modified. Not observable.
+- observableState: observable readonlyState. You can attach callbacks that fire on changes.
+- writeableState: observableState that you can modify, typesafe at runtime. Inner methods will do further work probably.
+- hardenedState: writableState (typesafe) that also does sanity checks before inner processing and throws on check failure.
+
+This will be a complete public state model in the DOM.
+
+And since it is needed for the solution below, that will be the first reference implementation using Micro Components. I hope the React world will be happy.
+
+Working with AI can be wonderful...
+
+## Start Session
+
+Me:
+**Do you remember our chat regarding Micro Components vs. existing frameworks?**
+
+ChatGPT:
+
+Yes, I remember our discussion! We talked about your approach to microcomponents as distinct from established frameworks, with a focus on smaller, modular, data-driven components that are stored in a hash attached to DOM elements (specifically in a _tb property in twoBirds or _mc for microcomponents). Your system emphasizes manual wiring, observability, and ease of interaction across components, making it different from React, Vue, or other component libraries that depend heavily on virtual DOMs, JSX, or hooks.
+
+Your components follow principles of separation of concerns and DRY by keeping interactions modular but flexible, and they use observables to trigger functions in other components, which can be linked in chains. Your approach allows a component-based design that integrates deeply into the DOM without the overhead of larger frameworks. And while existing frameworks typically follow a top-down data flow, your system allows bi-directional, observable properties that automatically update the DOM when data changes.
+
+Would you like to revisit any specific aspect, or compare further?
+
+
+## React
+
+Me:
+**There was something about React specifically?**
+
+
+ChatGPT:
+
+(...)
+
+### Manual Wiring vs. React’s Context and Hooks:
+React uses Context and hooks (like useState and useEffect) to manage data flow and lifecycle.
+
+Your approach leans on manual wiring for connecting data across microcomponents, avoiding the abstraction of hooks and allowing direct, observable-driven updates. This can make the flow of data more transparent and easier to trace in complex applications, whereas hooks can sometimes add complexity or obscurity when trying to understand data dependencies.
+
+### Component Reusability and Scaling:
+Both React and twoBirds support component-based architecture.
+
+However, twoBirds allows multiple microcomponents on a single DOM element, and each microcomponent is responsible for specific tasks, making scaling in large applications more modular and straightforward. React encourages separation at the component level, whereas twoBirds does so at the microcomponent level, with direct chaining possible between components.
+
+(...)
+
+Each of these aspects underlines twoBirds’ focus on minimalism, modularity, and developer control. These are different from React's abstraction and tooling-heavy approach, making your framework potentially more transparent and lightweight for specific use cases.
+
+Would you like to dive into any of these differences in more detail?
+
+
+## Prop Drilling
+
+Me:
+**In general there was a problem regarding carrying properties from a component close to the root of the document to a component that is much deeper into the DOM tree, do you remember that?**
+
+ChatGPT:
+
+Yes, I remember!
+
+We discussed the challenges in carrying properties or state from a root-level component down to deeply nested components. In React, this kind of deep property sharing can become cumbersome and often requires additional tools or patterns, such as:
+
+### Prop Drilling:
+React requires passing data through each level of components in the tree via props, a process known as prop drilling. This can lead to complex and hard-to-manage code, especially when the data isn’t relevant to every component in the chain.
+
+(...)
+
+In contrast, your twoBirds microcomponents have an alternative approach that makes it easier to pass properties throughout the DOM tree:
+
+### Direct Microcomponent Selectors:
+twoBirds includes selector methods (like .parents() and .descendants()) that allow components to access any microcomponent within the tree without explicit data passing. This capability enables deeply nested components to retrieve properties from higher-level components directly, bypassing the need to route data through intermediary components.
+
+### Observables for State Propagation:
+Since twoBirds uses observables, properties from a root component can be shared across components by observing changes directly. When the observable changes, all relevant components are notified and updated automatically. This is a natural data propagation method that doesn’t require explicit context or external state management.
+
+***( ...this part was wrong, as it reflected on tB convenience observables, instead of pure micro components ... )***
+
+### Manual Wiring for Control:
+
+**Because twoBirds relies on manual wiring, you can set up specific connections between components as needed.** This gives you fine-grained control over where and how data flows through the app without involving a top-level state or intermediary components, making it more scalable for larger apps without the need for a Context API or state library.
+
+(...)
+
+This structure offers a highly flexible, context-free solution for deep property sharing, making it an efficient alternative to prop drilling or global state libraries in many scenarios. Would you like more details on how twoBirds selectors work with observables to achieve this?
+
+
+## Generate Code
+
+Me:
+**Can you give an example of 2 react components that interact with each other using micro components? Give me the code of both components, using microomponents to exchange data**
+
+***( it took some further hinting, but in the end ChatGPT came up with this: )***
+
+
+ChatGPT:
+
+Here's the updated code:
+Parent Micro Component
+
+This component will receive a target DOM node and set a value that propagates down to its descendants:
+
+```javascript
+
+// Parent Micro Component
+class ParentMC extends MC {
+  constructor(targetNode) {
+    super(targetNode); // Receive and pass the target DOM node to the MC constructor
+  }
+
+  set value(newValue) {
+    // Send value to all descendants named "targetMC"
+    this.descendants("targetMC").forEach(descendant => descendant.data = newValue);
+  }
+}
+```
+
+Child Micro Component
+
+This component has a data setter that updates the internal React state in each child:
+
+```javascript
+
+// Child Micro Component
+class ChildMC extends MC {
+  constructor(targetNode, setReactState) {
+    super(targetNode); // Receive the target DOM node to be managed by MC
+    this.setReactState = setReactState;
+  }
+
+  set data(newValue) {
+    this.setReactState(newValue); // Update React state when data is set
+  }
+}
+```
+
+React Components Using Micro Components
+
+The following React setup attaches ParentMC and ChildMC to their respective DOM elements, using the parent DOM node to instantiate the micro components.
+Parent Component
+
+The parent component attaches an instance of ParentMC to the DOM node and sets its value based on inputValue.
+
+```javascript
+
+import React, { useState, useRef, useEffect } from 'react';
+import { MC } from '@twobirds/microcomponents';
+
+const ParentComponent = () => {
+  const [inputValue, setInputValue] = useState("");
+  const parentRef = useRef(null);
+
+  useEffect(() => {
+    const parentMC = new ParentMC(parentRef.current); // Pass the DOM node to ParentMC
+    MC.add(parentRef.current, 'parentMC', parentMC);
+
+    // Update value in ParentMC whenever inputValue changes
+    parentMC.value = inputValue;
+  }, [inputValue]);
+
+  return (
+    <div ref={parentRef}>
+      <input
+        type="text"
+        value={inputValue}
+        onChange={(e) => setInputValue(e.target.value)}
+        placeholder="Type to send data to children"
+      />
+      <ChildComponent />
+    </div>
+  );
+};
+```
+
+Child Component
+
+The child component attaches an instance of ChildMC, which updates its state whenever data is set.
+
+```javascript
+
+const ChildComponent = () => {
+  const [childData, setChildData] = useState("");
+  const childRef = useRef(null);
+
+  useEffect(() => {
+    const childMC = new ChildMC(childRef.current, setChildData); // Pass DOM node and state setter to ChildMC
+    MC.add(childRef.current, 'targetMC', childMC);
+  }, []);
+
+  return (
+    <div ref={childRef}>
+      <h3>Received Data:</h3>
+      <p>{childData}</p>
+    </div>
+  );
+};
+```
+
+***( ... I cannot tell about the react part, but the micro coomponent code is spot on. Like WLAN on the DOM :-) )***
+
+
+**ChatGPT can produce errors. Check the information.**
+
+## ... yes I do :-)
+
+***( ... but it was right on the money in the end. I love AI, albeit with a healthy grain of sceptic salt. )***
+
+***( ... and I asked about MCs and Angular likewise, and it directly pointed me to a NG module problem that can also be solved. It even came up with sample code. )***

package/public/documentation/usage.md

@@ -0,0 +1,142 @@
+# Micro Component Management
+
+This system allows you to attach, manage, and interact with micro components.
+
+**Micro Components** can literally be anything you can put into an object as a property.
+
+Also it has selectors to find micro components in the DOM. It consists of a single class `MC`.
+
+## Summary of MC() Methods
+
+- **Static Methods:**
+  - `MC.add( target, key, element)`: Attach a top level micro component to an HTMLElement.
+  - `MC.remove( target, key )`: Detach a top level micro component from an HTMLElement.
+  - `MC.siblings( target )`: get top level micro components from an HTMLElement.
+
+- **Instance Methods:**
+  - `add( key, element )`: Attach a private Micro Component to a Micro Component.
+  - `remove( key )`: Detach a private Micro Component from a Micro Component.
+  - `siblings(search?)`: Retrieve sibling micro components.
+  - `parent(search?)`: Get parent top level micro components.
+  - `parents(search?)`: Get all ancestor top level micro components.
+  - `children(search?)`: Retrieve child top level micro components.
+  - `descendants(search?)`: Get all descendant top level micro components.
+
+**Micro Components** will most likely be **class instances** that expose inner methods **or an observable collection** for data driven workflows, e.g. business process logic.
+
+## Typical Workflow
+
+1. **Attach micro components** to elements using `MC.add()`.
+2. **Access** micro components by their property key or navigating through DOM (e.g., `siblings()`, `parents()`, `children()`, etc.) **and use their inner functionality**.
+3. **Manipulate** micro components by adding or removing them as needed or change their properties/call their methods.
+
+
+## Hints
+
+- **All static methods handle top level Micro Components. These are PUBLIC, that is they are visible in the DOM elements _mc property and usually have an interface.**
+
+- **All MC instance methods handle inner Micro Components. These are PRIVATE, that is they are not visible in the DOM elements _mc property.**
+
+- **Micro Components can recursively contain Micro Components. Just like npm and the node_modules directory.**
+
+
+## Attaching a top level Micro Component to a DOM element
+
+To attach a micro component to an HTML element, use the `MC.add()` static function.
+
+### Example Usage:
+```javascript
+const myElement = document.getElementById('myDiv');
+
+// Attach a micro component (most often a class instance, here a simple object for simplicity) with a specific key
+MC.add( myElement, 'myComponent', { name: 'Mike' } );
+```
+
+- After you added a micro component using this function, the HTMLElement will contain a  property `_mc` which is a MC() class instance that offers some methods.
+- Also the HTMLElement then has an attribute _mc which will indicate that at least one micro component is attached to this dom element.
+
+## Removing a top level Micro Component from a DOM element
+
+Micro components can be removed using the `MC.remove()` static method.
+
+### Removing a Micro component:
+```javascript
+MC.remove( myDomElement, 'myComponent');
+```
+
+**When all micro components are removed** (the _mc object has no more properties), the `_mc` **attribute is also removed** from the HTML element. The `_mc` **property persists**.
+
+
+## Retrieve all top level Micro Components from a DOM element
+
+The `MC.siblings()` method retrieves all top level micro components attached to the same DOM element.
+
+### Example:
+```javascript
+const target = document.querySelector( 'div' );
+const siblings = MC.siblings( target );
+console.log(siblings);  // Logs an array of top level sibling micro components
+```
+
+To retrieve a specific micro component by its key:
+```javascript
+const target = document.querySelector( 'div' );
+const siblings = MC.siblings( target, 'myOtherComponent' );
+console.log(siblings);  // Logs an array containing a top level sibling micro component, if its key matches the search string
+```
+
+
+## Retrieving Sibling Micro components
+
+The `.siblings()` method retrieves all micro components attached to the same DOM element.
+
+### Example:
+```javascript
+const siblings = myElement._mc.siblings();
+console.log(siblings);  // Logs an array of sibling micro components
+```
+
+To retrieve a specific micro component by its key:
+```javascript
+const specificSibling = myElement._mc.siblings('anotherComponent');
+```
+
+
+- **The following methods hop over HTMLElements that contain no micro component.**
+
+
+## 4. Navigating Parent and Ancestor Micro components
+
+The `_mc.parent()` and `_mc.parents()` methods allow you to retrieve micro components attached to parent elements.
+
+### Example:
+```javascript
+const parentMc = myElement._mc.parent();
+console.log(parentMc);  // Logs micro components closest nachestor that has microcomponents
+
+const allAncestorsMc = myElement._mc.parents();
+console.log(allAncestorsMc);  // Logs all ancestor micro components up to document
+```
+
+To retrieve a specific micro component attached to the parent or ancestors:
+```javascript
+const specificAncestorMc = myElement._mc.parents('myComponent');
+```
+
+## 5. Retrieving Child and Descendant Micro components
+
+The `_mc.children()` and `_mc.descendants()` methods retrieve micro components attached to child elements or any descendants.
+
+### Example:
+```javascript
+const childMicro components = myElement._mc.children();
+console.log(childMicro components);  // Logs an array of nearest child micro components
+
+const descendantMicro components = myElement._mc.descendants();
+console.log(descendantMicro components);  // Logs micro components attached to all descendants
+```
+
+To search for a specific micro component by key:
+```javascript
+const specificMc = myElement._mc.<someComponent>;
+```

package/public/documentation/why.md

@@ -0,0 +1,25 @@
+
+## Why would I give this a try?
+
+It is lightweight, proven and can yield positive results immediatly.
+
+
+### **As the CTO**:
+
+- **Reusability**: this works with every Javascript framework that allows for DOM access, and it will work as long as the DOM exists in browsers. That is, forever.
+- **Scalability**: scales perfectly by design.
+- **Interoperability**: where many teams in different projects should share specific business or UI logic, you want to have something that works in any JS framework you use.
+
+### **As a Project Manager**:
+
+- **Separation of Concerns**: since this is a modular approach you can **split UI logic from Business logic** and let diffent teams work on each.
+- using this, you can **work with external developers without the need to give them access to your projects code repository**.
+- you will find out that this allows your project to **become independent from the "tools hell"**. You tend to use **DIY** modules where you had tools before.
+
+### **As a Javascript Developer**:
+
+- The learning curve to use this is more than shallow. 1 hour should be enough.
+- This is based on **plain Javascript/Typescript, HTML and CSS**. There is no abstraction layer.
+- From the very start **it is fun to work with**. You are back in control of your code without bigger frameworks, but you are able to interact with them.
+- You can **work for any customer right away**. **No training on their system required**, just fulfill their micro component requirements.
+- Over time, you can **build your own framework or functional libraries** from scratch.

package/public/test.js

@@ -143,14 +143,16 @@ class MC {
         return getMicroComponents([...myDomElements], search);
     }
 }
-// create test page
-document.body.innerHTML = `<div class="level_1"><span><div class="level_2"><span><div class="level_3"><span><div class="level_4"><span><div class="level_5"></div></span></div></span></div></span></div></span></div>`;
-let elements = [...document.querySelectorAll("div")].reverse();
-elements.forEach((e) => (e.innerHTML = e.innerHTML.repeat(5)));
-document.body.innerHTML = document.body.innerHTML.repeat(5);
-document.body.innerHTML =
-    document.body.innerHTML +
-        "<span>F12 opens the debugger, console has some manual tests...</span>";
+// create test page if necessary, otherwise test what is present
+if (window.location.hostname.indexOf("gitlab") > -1) {
+    document.body.innerHTML = `<div class="level_1"><span><div class="level_2"><span><div class="level_3"><span><div class="level_4"><span><div class="level_5"></div><div class="level_5"></div><div class="level_5"></div><div class="level_5"></div><div class="level_5"></div></span></div></span></div></span></div></span></div>`;
+    let elements = [...document.querySelectorAll("div")].reverse();
+    elements.forEach((e) => (e.innerHTML = e.innerHTML.repeat(5)));
+    document.body.innerHTML = document.body.innerHTML.repeat(5);
+    document.body.innerHTML =
+        document.body.innerHTML +
+            "<span>F12 opens the debugger, console has some manual tests...</span>";
+}
 // create an inner micro component class
 class MyInnerMC extends MC {
     constructor(target) {
@@ -178,9 +180,9 @@ class MyMC extends MC {
 }
 console.time("MC creation time");
 // get some element from the DOM
-const element = document.querySelector("div");
+const domElement = document.querySelector("div");
 // Add the custom micro component instance to the target element
-let topLevelMC = MC.add(element, "myFirstMC", new MyMC(element));
+MC.add(domElement, "myFirstMC", new MyMC(domElement));
 // Add the custom micro component instance to every div
 document.querySelectorAll("div").forEach((e) => {
     MC.add(e, "myPublicMC1", new MyMC(e));
@@ -189,20 +191,20 @@ document.querySelectorAll("div").forEach((e) => {
 console.timeEnd("MC creation time");
 let c = document.querySelectorAll("[_mc]");
 console.info("number of DOM nodes:", document.querySelectorAll("*").length, "\nnumber of DOM nodes containing micro components:", c.length, "\nnumber of top level micro components:", c.length * 2 + 1, // TODO write reducer
-"\nnumber of top level & inner micro components:", c.length * 3 + 2 // TODO write reducer
+"\nnumber of top level & inner micro components:", c.length * 6 + 2 // TODO write reducer
 );
-console.log("ROOT element", element);
-console.log("-> ._mc", element._mc);
-console.log("-> _mc.myMC", element._mc.myMC);
-console.log("-> _mc.myFirstMC._mc (MC.debug = false)", element._mc.myFirstMC._mc);
+console.warn("domElement = first DIV element:", domElement);
+console.log("domElement\n  ._mc", domElement._mc);
+console.log("domElement\n  ._mc\n  .myFirstMC", domElement._mc.myFirstMC);
+console.log("domElement\n  ._mc\n  .myFirstMC\n  ._mc (MC.debug = false)", domElement._mc.myFirstMC._mc);
 MC.debug = true;
-console.log("-> _mc.myFirstMC._mc (MC.debug = true)", element._mc.myFirstMC._mc);
+console.log("domElement\n  ._mc\n .myFirstMC\n  ._mc  (MC.debug = true)", domElement._mc.myFirstMC._mc);
 MC.debug = false;
 /*
 test selectors
 */
 let sc = c[2]._mc.myPublicMC1; // 3rd level DIV micro component
-console.info("sc", sc);
+console.warn("sc = some div in the middle of the tree, level 3 of 5", sc);
 console.log("number of sc parents (expect 5)", sc.parents());
 console.log("number of sc parent (expect 2)", sc.parent());
 console.log("sc PUBLIC siblings (expect 2)", sc.target.className, Object.keys(sc.target._mc), sc.target._mc);
@@ -211,4 +213,4 @@ MC.debug = true;
 console.log("sc PRIVATE siblings (MC.debug = true, expect 1)", Object.keys(sc._mc).length, sc._mc);
 MC.debug = false;
 console.log("number of sc children (expect 10)", sc.children());
-console.log("number of sc descendants (expect 60)", sc.descendants());
+console.log("number of sc descendants (expect 260)", sc.descendants());