@twobirds/microcomponents 0.0.50 → 0.0.51

package/public/documentation/observe.md

@@ -1,317 +0,0 @@
-Okay, I understand. You want me to modify the code examples within the Markdown documentation so that they demonstrate how to use the observe() functionality inside a microcomponent's constructor (specifically, an MC constructor). I'll also keep the output as a JavaScript variable assignment (let md = "...";).
-
-Here's the updated version of the code, with the examples adapted to be used within an MC constructor:
-JavaScript
-
-let md = `#   Observable Properties Functionality (`observe()`)
-
-This document explains the `observe()` functionality, a utility for making properties of JavaScript objects observable. When an observable property's value changes, registered callback functions are automatically notified, enabling reactive data binding and UI updates.
-
-## Table of Contents
-
-- [Core Concept](#core-concept)
-- [Function Signature](#function-signature)
-- [How it Works](#how-it-works)
-- [Key Features](#key-features)
-- [Usage](#usage)
-  - [Making Properties Observable (within MC Constructor)](#making-properties-observable-within-mc-constructor)
-  - [Registering Observers (`observe()` method on Observable) (within MC Constructor)](#registering-observers-observe-method-on-observable-within-mc-constructor)
-  - [Binding Observable Objects to the DOM (`bind()` method on Observable Object) (within MC Constructor)](#binding-observable-objects-to-the-dom-bind-method-on-observable-object-within-mc-constructor)
-  - [Manually Notifying Observers (`notify()` method on Observable) (within MC Constructor)](#manually-notifying-observers-notify-method-on-observable-within-mc-constructor)
-- [Examples of Useful Usage (within MC Constructor)](#examples-of-useful-usage-within-mc-constructor)
-  - [Simple Data Binding (within MC Constructor)](#simple-data-binding-within-mc-constructor)
-  - [Automatic UI Updates in Web Components (within MC Constructor)](#automatic-ui-updates-in-web-components-within-mc-constructor)
-  - [Centralized State Management (within MC Constructor)](#centralized-state-management-within-mc-constructor)
-  - [Form Input Synchronization (within MC Constructor)](#form-input-synchronization-within-mc-constructor)
-- [Considerations](#considerations)
-  - [Performance](#performance)
-  - [Deep Object Observation](#deep-object-observation)
-  - [Type Changes](#type-changes)
-- [Related Concepts](#related-concepts)
-
-## <a name="core-concept"></a>Core Concept
-
-The `observe()` function transforms specified properties of a JavaScript object into "observable" properties. This means that changes to these properties can be intercepted, and registered listeners (callbacks) can be automatically invoked to react to these changes. This pattern is fundamental for implementing reactive programming paradigms, where UI or other parts of an application automatically update in response to data modifications.
-
-## <a name="function-signature"></a>Function Signature
-
-```
-observe(target: LooseObject, propertyName?: string): LooseObject
-```
-
-- `target: LooseObject`: The JavaScript object whose properties you want to make observable. `LooseObject` is likely a type definition for a generic object (e.g., `{ [key: string]: any }`).
-- `propertyName?: string`: An optional string specifying a single property of the `target` object to make observable. If this argument is omitted, the function attempts to make all own properties of the `target` observable.
-- `returns: LooseObject`: The original `target` object, now with the specified (or all) properties made observable.
-
-## <a name="how-it-works"></a>How it Works
-
-The `observe()` function achieves observability by:
-
-1.  **Redefining Properties:** It uses `Object.defineProperty` to redefine the getter and setter of the `target` property (or properties).
-2.  **Creating an `Observable` Wrapper:** For each observable property, it creates an instance of a dynamically generated `Observable` class that extends the original constructor of the property's value (e.g., `String`, `Number`, `Object`, `Array`). This wrapper holds the actual value and manages a list of observer callbacks.
-3.  **Intercepting Access (Getter):** When an observable property is accessed, the getter returns the `Observable` wrapper instance. For observable objects, it also sets up a debounced function to check for deep changes within the object at a later point.
-4.  **Intercepting Modification (Setter):** When an observable property is assigned a new value, the setter:
-    - Checks if the type of the new value is compatible with the old value.
-    - Creates a new `Observable` wrapper with the new value.
-    - Notifies all registered observer callbacks associated with that property (or the entire observable object, depending on how observation is set up).
-5.  **Managing Callbacks:** Each `Observable` wrapper maintains a list of callback functions registered through its `observe()` method. These callbacks are invoked when the observable's value changes.
-6.  **DOM Binding (`bind()`):** For observable objects, the `bind()` method facilitates automatic synchronization with placeholders in the DOM using the `Placeholders` DOM Component.
-
-## <a name="key-features"></a>Key Features
-
-- Selective Observability: You can choose to make specific properties observable or observe all properties of an object.
-- Type Checking: The setter attempts to prevent changing the data type of an observable property.
-- Callback Mechanism: Allows registering multiple functions to be notified of changes.
-- DOM Binding Integration: Provides a `bind()` method for observable objects to automatically update DOM elements containing placeholders.
-- Debounced Deep Change Detection: For observable objects, changes within the object are detected using a debounced deep equality check to optimize performance.
-
-## <a name="usage"></a>Usage
-
-### <a name="making-properties-observable-within-mc-constructor"></a>Making Properties Observable (within MC Constructor)
-
-To make properties of an object observable within an MC constructor, call the `observe()` function with the object as the `target`. You can optionally specify a `propertyName` to observe only a single property.
-
-```javascript
-import { observe } from './observables.js'; // Assuming your observe() function is in this file
-import { MC } from './MC.js'; // Import your MC class
-
-class MyComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.myData = {
-			name: 'Initial Name',
-			count: 0,
-			settings: {
-				theme: 'light',
-			},
-		};
-
-		observe(this.myData); // Make all properties of this.myData observable
-
-		this.myData.name = 'Updated Name'; // Observers of this.myData.name will be notified
-		this.myData.count++; // Observers of this.myData.count will be notified
-		this.myData.settings.theme = 'dark'; // Observers of this.myData.settings will be notified
-	}
-}
-```
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyConfigComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.config = {
-			apiKey: 'your_api_key',
-			isEnabled: true,
-		};
-
-		observe(this.config, 'apiKey'); // Only make the apiKey property observable
-
-		this.config.apiKey = 'new_api_key'; // Observers of this.config.apiKey will be notified
-		this.config.isEnabled = false; // Observers of this.config.isEnabled will NOT be directly notified by observe()
-	}
-}
-```
-
-### <a name="registering-observers-observe-method-on-observable-within-mc-constructor"></a>Registering Observers (`observe()` method on Observable) (within MC Constructor)
-
-When a property becomes observable, its getter will return an `Observable` wrapper. This wrapper has an `observe()` method to register callback functions that will be executed when the observable's value changes.
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyStateComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.state = {
-			message: 'Hello',
-		};
-		observe(this.state);
-
-		this.state.message.observe((newValue) => {
-			console.log('Message changed to:', newValue);
-		});
-
-		this.state.message = 'World'; // Output: Message changed to: World
-	}
-}
-```
-
-### <a name="binding-observable-objects-to-the-dom-bind-method-on-observable-object-within-mc-constructor"></a>Binding Observable Objects to the DOM (`bind()` method on Observable Object) (within MC Constructor)
-
-If an observable property's value is an object, it will have a `bind()` method. This method allows you to automatically connect the observable object's properties to placeholders (`{propertyName}`) within a specified DOM element (or its descendants). This relies on the `Placeholders` DOM Component.
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyUserDataComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.userData = {
-			firstName: 'John',
-			lastName: 'Doe',
-		};
-		observe(this.userData);
-
-		this.outputElement = document.getElementById('output'); // Assuming you have an element with id="output"
-		this.userData.bind(this.outputElement);
-
-		this.outputElement.innerHTML = `
-            <p>First Name: {firstName}</p>
-            <p>Last Name: {lastName}</p>
-        `;
-
-		this.userData.firstName = 'Jane'; // The text content of the first <p> will automatically update
-	}
-}
-```
-
-### <a name="manually-notifying-observers-notify-method-on-observable-within-mc-constructor"></a>Manually Notifying Observers (`notify()` method on Observable) (within MC Constructor)
-
-The `Observable` wrapper also has a `notify()` method that you can call manually to force the registered observers to be executed. This can be useful in specific scenarios where changes might not be directly detected by the setter (though the debounced deep check for objects aims to handle this).
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyDataItemsComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.data = {
-			items: [],
-		};
-		observe(this.data);
-
-		this.data.items.observe(() => {
-			console.log('Items array changed:', this.data.items);
-		});
-
-		// Directly modifying the array might not always trigger the setter
-		this.data.items.push('new item');
-		this.data.items.notify(); // Manually trigger the observers
-	}
-}
-```
-
-## <a name="examples-of-useful-usage-within-mc-constructor"></a>Examples of Useful Usage (within MC Constructor)
-
-### <a name="simple-data-binding-within-mc-constructor"></a>Simple Data Binding (within MC Constructor)
-
-Observables are excellent for simple data binding scenarios where you want to keep different parts of your application synchronized with a piece of data.
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyInputComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.viewModel = {
-			inputValue: '',
-		};
-		observe(this.viewModel);
-
-		this.inputElement = document.getElementById('myInput'); // Assuming you have an input with id="myInput"
-		this.outputSpan = document.getElementById('outputValue'); // Assuming you have a span with id="outputValue"
-
-		this.inputElement.addEventListener('input', (event) => {
-			this.viewModel.inputValue = event.target.value;
-		});
-
-		this.viewModel.inputValue.observe((newValue) => {
-			this.outputSpan.textContent = newValue;
-		});
-	}
-}
-```
-
-### <a name="automatic-ui-updates-in-web-components-within-mc-constructor"></a>Automatic UI Updates in Web Components (within MC Constructor)
-
-As demonstrated in the `my-tag` example, observables can be used to automatically update the template of a web component when its internal data changes, leading to reactive and dynamic UIs.
-
-### <a name="centralized-state-management-within-mc-constructor"></a>Centralized State Management (within MC Constructor)
-
-Observables can form the basis of a simple state management system. By making the application's state an observable object, different components can observe relevant parts of the state and automatically update when those parts change.
-
-```javascript
-import { observe } from './observables.js';
-import { MC } from './MC.js';
-
-class MyAppStateComponent extends MC {
-	constructor(target) {
-		super(target);
-
-		this.appState = {
-			user: null,
-			isLoading: false,
-			errorMessage: null,
-		};
-		observe(this.appState);
-
-		// Component A observes the user
-		this.appState.user.observe((user) => {
-			if (user) {
-				console.log('User logged in:', user.name);
-				// Update UI to show user info
-			} else {
-				console.log('User logged out');
-				// Update UI to reflect logged out state
-			}
-		});
-
-		// Component B observes the loading state
-		this.appState.isLoading.observe((loading) => {
-			if (loading) {
-				console.log('Loading...');
-				// Show loading indicator
-			} else {
-				console.log('Loading complete.');
-				// Hide loading indicator
-			}
-		});
-
-		// Actions can update the state
-		this.loginUser = (username, password) => {
-			this.appState.isLoading = true;
-			// ... perform login logic ...
-			setTimeout(() => {
-				this.appState.user = { name: username };
-				this.appState.isLoading = false;
-			}, 1000);
-		};
-
-		this.loginUser('john.doe', 'password');
-	}
-}
-```
-
-## <a name="considerations"></a>Considerations
-
-### <a name="performance"></a>Performance
-
-While observables provide a convenient way to handle data changes, be mindful of performance, especially with deeply nested objects or a large number of observers. Excessive notifications and deep equality checks can potentially impact performance.
-
-### <a name="deep-object-observation"></a>Deep Object Observation
-
-The provided `observe()` implementation includes a debounced deep equality check for object properties. However, for very complex or frequently changing nested objects, you might consider more optimized deep observation techniques if performance becomes an issue.
-
-### <a name="type-changes"></a>Type Changes
-
-The setter in the `observe()` function attempts to prevent changing the data type of an observable property. Be aware of this limitation when working with observable data.
-
-## <a name="related-concepts"></a>Related Concepts
-
-- Reactive Programming: A programming paradigm centered around the propagation of change.
-- Data Binding: The process of synchronizing data between different parts of an application, often between the model and the view.
-- DOM Components: Reusable units of behavior associated with DOM elements, as provided by the Microcomponent Framework.
-- Placeholders: Dynamic markers within HTML that can be automatically updated with data.

package/public/documentation/proposal_draft.md

@@ -1,37 +0,0 @@
-### 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

@@ -1,207 +0,0 @@
-# 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...)***
-
-## 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 Micro Components support component-based architecture.
-
-However, Micro Components 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 Micro Components does so at the microcomponent level, with direct chaining possible between components.
-
-(...)
-
-Each of these aspects underlines Micro Components’ 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 Micro Components microcomponents have an alternative approach that makes it easier to pass properties throughout the DOM tree:
-
-### Direct Microcomponent Selectors:
-Micro Components 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.
-
-(...)
-
-### Manual Wiring for Control:
-
-**Because Micro Components rely 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 Micro Components 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
-import { MC } from '@twobirds/microcomponents';
-
-// 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
-import { MC } from '@twobirds/microcomponents';
-
-// 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';
-import { ParentMC } from '@myCompany/ParentMC';
-
-const ParentComponent = () => {
-  const [inputValue, setInputValue] = useState("");
-  const parentRef = useRef(null);
-  const parentMC = new ParentMC( parentRef );
-  const sender = MC.add(parentRef.current, 'parentMC', parentMC);
-
-  useEffect(() => {
-    // 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
-import React, { useState, useRef } from 'react';
-import { MC } from '@twobirds/microcomponents';
-import { ChildMC } from '@myCompany/ChildMC';
-
-
-const ChildComponent = () => {
-  const [childData, setChildData] = useState("");
-  const childRef = useRef(null);
-  const childMC = new ChildMC( childRef, setChildData );
-  const receiver = MC.add(childRef.current, 'childMC', 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. )***