@twobirds/microcomponents 0.0.10 → 0.0.14

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,369 @@
+# 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**
+
+***( The first result as shown below is edited and fed back to outline errors ChatGPT made, so this is not the original answer but my corrected feed back )***
+
+***( ChatGPTs errors were based on the assumption that MCs behave like twoBirds micro components, which turn properties in convenience observables automatically. These can be accessed like simple properties, but still work as observables. )***
+
+Skip to [Final Version](#final-version) if you dont want to see my intermediate corrections.
+
+
+ChatGPT:
+
+Here’s an example of two React components interacting with each other using the Micro Components (MC) approach as you’ve described. In this example, the microcomponents are responsible for sharing and updating data across the two React components without relying on React's props or context.
+
+In this scenario, we’ll have two React components:
+
+ParentComponent: Contains a microcomponent managing shared state.
+ChildComponent: Retrieves and observes updates to that shared state through the microcomponent system.
+
+The Micro Component framework will handle state observability, allowing ChildComponent to respond to changes in ParentComponent.
+
+### Step 1: Set Up Micro Components for State Sharing
+
+First, let’s create a microcomponent to hold shared data. This MC will be instantiated in ParentComponent and observed in ChildComponent.
+
+```javascript
+
+// SharedStateMC.js
+import {MC} from '@twobirds/microcomponents';
+
+class SharedStateMC extends MC {
+    constructor(target) {
+        super(target);
+
+        // Define an observable property for shared data
+        // this part is wrong: ChatGPT assumed this property is a twoBirds convenience observable property, which MCs dont do automatically.
+        // lets for now assume it is
+        this.sharedData = "Initial data from Parent"; // this in fact is assumed to be an observable in tB, as any property defined in the constructor.
+        // Also, this observable property would be runtime type safe, BTW.
+        // This is important for public MCs, as they expose a PUBLIC interface to internal properties for EVERYBODY to use at runtime. So:
+        //  document.getElementById("parent-root")._mc.sharedState.sharedData = 'My hilarious string';
+        // ... this will trigger the callbacks associated with it
+        // MCs ACT AS INTERFACES!
+    }
+
+}
+
+export default SharedStateMC;
+```
+
+### Step 2: Create ParentComponent with Micro Component for Shared State
+
+In ParentComponent, we’ll create an instance of SharedStateMC and attach it as a microcomponent on the main DOM element of this component.
+
+```javascript
+
+// ParentComponent.js
+import React, { useEffect } from 'react';
+import SharedStateMC from './SharedStateMC';
+
+function ParentComponent() {
+    useEffect(() => {
+        // Attach SharedStateMC to the main component div
+        const parentElement = document.getElementById("parent-root");
+        const sharedState = MC.add( parentElement, 'sharedState', new SharedStateMC( parentElement ) );
+
+        // Simulate updating data after 3 seconds
+        // changing a tB convenience observable really is as easy as this, also it is type-safe at runtime
+        setTimeout(() => {
+            sharedState.sharedData = "Updated data from Parent";
+        }, 3000);
+    }, []);
+
+    return (
+        <div id="parent-root">
+            <h1>Parent Component</h1>
+            <p>Check ChildComponent for updated data.</p>
+            <ChildComponent />
+        </div>
+    );
+}
+
+export default ParentComponent;
+```
+
+### Step 3: Create ChildComponent to Observe and Display Shared Data
+
+In ChildComponent, we’ll access the SharedStateMC instance created by ParentComponent using DOM selectors and observe the sharedData property.
+
+```javascript
+
+// ChildComponent.js
+import React, { useEffect, useState } from 'react';
+
+function ChildComponent() {
+    const [data, setData] = useState("");
+
+    useEffect(() => {
+        // Access the microcomponent instance on the parent's DOM element
+        const parentElement = document.getElementById("parent-root");
+        const sharedStateMC = parentElement._mc.sharedState;
+
+        // Initial data load
+        setData(sharedStateMC.sharedData);
+
+        // Observe changes to shared data in SharedStateMC
+        // this isn't quite right, for reasons mentioned above, but close
+        sharedStateMC.observe((newData) => {
+            setData(newData);
+        });
+    }, []);
+
+    return (
+        <div>
+            <h2>Child Component</h2>
+            <p>Data from Parent: {data}</p>
+        </div>
+    );
+}
+
+export default ChildComponent;
+```
+
+### How It Works
+
+In ParentComponent: An instance of SharedStateMC is created and attached to the main DOM element with an ID parent-root.
+After 3 seconds, it updates sharedData to a new value.
+
+In ChildComponent: We access the SharedStateMC instance via the _mc property of the parent element and observe sharedData.
+When sharedData changes, ChildComponent re-renders with the updated data.
+
+### Explanation
+
+Observable Property: sharedData is an observable property within SharedStateMC.
+This allows the ChildComponent to subscribe and react to changes without using React's props or context.
+Direct DOM Access:
+The ChildComponent directly accesses ParentComponent's microcomponent via document.getElementById("parent-root")._mc.
+
+This pattern effectively mimics cross-component communication in React but using the microcomponents as an intermediary for data sharing.
+
+
+## Final Version
+
+Me:
+**assume this revised markup... can you spot the difference? ( My feedback code from above was added )**
+
+ChatGPT:
+
+You’ve provided a revised example that incorporates microcomponents with clearer runtime type safety and public interfaces. Let’s review the differences and corrections made in this version:
+
+***( ChatGPT explains my changes )***
+
+Here’s the final, corrected code with these changes fully implemented:
+
+Final Revised Code
+SharedStateMC.js
+
+```javascript
+import { MC } from '@twobirds/microcomponents';
+
+class SharedStateMC extends MC {
+    constructor(target) {
+        super(target);
+        // Define an observable property for shared data with runtime type safety
+        this.sharedData = "Initial data from Parent";
+    }
+}
+
+export default SharedStateMC;
+```
+
+
+ParentComponent.js
+
+```javascript
+import React, { useEffect } from 'react';
+import SharedStateMC from './SharedStateMC';
+import { MC } from '@twobirds/microcomponents';
+
+function ParentComponent() {
+    useEffect(() => {
+        const parentElement = document.getElementById("parent-root");
+
+        // Attach SharedStateMC instance to parent element with 'sharedState' key
+        const sharedState = MC.add(parentElement, 'sharedState', new SharedStateMC(parentElement));
+
+        // Updating shared data after 3 seconds with observable property syntax
+        setTimeout(() => {
+            sharedState.sharedData = "Updated data from Parent";
+        }, 3000);
+    }, []);
+
+    return (
+        <div id="parent-root">
+            <h1>Parent Component</h1>
+            <p>Check ChildComponent for updated data.</p>
+            <ChildComponent />
+        </div>
+    );
+}
+
+export default ParentComponent;
+```
+
+
+ChildComponent.js
+
+```javascript
+import React, { useEffect, useState } from 'react';
+
+function ChildComponent() {
+    const [data, setData] = useState("");
+
+    useEffect(() => {
+        const parentElement = document.getElementById("parent-root");
+        const sharedStateMC = parentElement._mc.sharedState;
+
+        // Initial data load
+        setData(sharedStateMC.sharedData);
+
+        // Observing updates to sharedData property
+        sharedStateMC.sharedData.observe((newData) => {
+            setData(newData);
+        });
+    }, []);
+
+    return (
+        <div>
+            <h2>Child Component</h2>
+            <p>Data from Parent: {data}</p>
+        </div>
+    );
+}
+
+export default ChildComponent;
+```
+
+**Summary of Changes**
+
+Observables: The sharedData property in SharedStateMC is now noted to be observable and accessible as a public interface.
+
+Microcomponent Attaching: Using MC.add clarifies the attachment of the SharedStateMC instance to parentElement.
+
+Runtime Type Safety: The property remains observable, allowing callbacks on sharedData in ChildComponent.
+
+This implementation accurately reflects the design principles and interfaces for twoBirds MCs, allowing cross-component data sharing while ensuring type safety and a clean observable setup.
+
+
+**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/{docs/functions → functions}/microcomponents_es3.__isEmpty.html

@@ -27,7 +27,7 @@
 <h5>obj: <span class="tsd-signature-type">any</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">boolean</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://gitlab.com/twoBirds/microcomponents/-/blob/cb1aec4/src/microcomponents.es3.js#L3">src/microcomponents.es3.js:3</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://gitlab.com/twoBirds/microcomponents/-/blob/f72dc84/src/microcomponents.es3.js#L3">microcomponents.es3.js:3</a></li></ul></aside></li></ul></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">