@twobirds/microcomponents 0.0.12 → 0.0.14

package/assets/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twobirds/microcomponents",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Micro Components Organization Class",
   "main": "microcomponents.js",
   "sideEffects": false,
@@ -10,7 +10,7 @@
     "prep": "cp -R assets/* public || true; cp src/* build || true;",
     "build": "npm run clean; npm run prep; tsc; npm run minify; npm run copyToDist;",
     "minify": "jsmin -o build/microcomponents.es3.min.js ./src/microcomponents.es3.js;jsmin -o build/microcomponents.min.js build/microcomponents.js;",
-    "copyToDist": "cp -R assets/* public || true; cp build/* dist; cp build/microcomponents.js public; cp build/test.js public; cp MicroComponents.svg dist; cp MicroComponents.svg public/fiddle;"
+    "copyToDist": "cp -R assets/* public || true; cp build/micro* dist; cp build/microcomponents.js public; cp build/test.js public; cp MicroComponents.svg dist; cp MicroComponents.svg public/fiddle;"
   },
   "author": "",
   "license": "ISC",

package/public/documentation/functional_requirements.md

@@ -0,0 +1,8 @@
+## Functional Requirements
+
+- I want to **enrich a standard HTMLElement instance or any object with encapsuled and modular javascript**, without having to resort to web components or big frameworks.
+- I want to have an **interface** into this functionality that I can both tight and loosely couple.
+- I want to **import and use Micro Components in any framework** that allows for direct DOM access.
+- I want **a single location** in an HTMLElement instance where all this functionality is **stored and sufficiently organized**.
+- I want to be able to use **selectors** to find those instances in the DOM.
+- All this must stricly follow **web standards**.