@twobirds/microcomponents/README.md

Micro Components Organization Class

![logo](./MicroComponents.svg)

## MICRO COMPONENTS

**This code aims at improving Javascript modularity and encapsulation**.

Micro Components are built on **OOP** for structure, so you should embrace **DRY, KISS and SOLID** principles. That said, OOP is not a religion here, in fact you can do FP also. MCs provide a structure for your code, no more. It is agnostic as to what code you put in this structure.

Its basic principle is **composition over inheritance**. So: using OOP its recommended you do not extend your own classes, as it is not needed.

Also it helps to embrace **DIY** (Do It Yourself) **over Toolchains**, but this is up to your personal preference.

You can use **Vanilla JS or Typescript** or both in your project. For example you could use plain JS for rapid prototyping functionalities, then convert to TS for production.

## Think **Building Blocks**

In general this is a **HTML / Web Standards first** system. There is almost no abstraction, especially not for templating, except state binding to the DOM via simple placeholders.

When coding with this system, you create classes that extend either the **[MC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads#mc-class-extends-mcbase)** or **[DC](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads#dc-class-extends-mcbase)** superclasses provided here. These classes provide the structure you need to build your wonderland. 

You **attach instances of your classes to any HTMLElement**, and there can be as many as you want connected to a single HTML tag. In an almost literal sense they work like childrens building blocks, where a chest full of unassuming parts lets you compose whatever functionality lies in your imagination.

Also you can easily **define JS custom elements**. Since these are just another instance of a DC internally, you can enhance them even at runtime, as they are displayed in the browser.

## Principles

This systems **modular** approach gives you full control over your software, without the need to rely on other frameworks. 

On the other hand, its **minimalistic** stance enables you to use the resulting functionality in any other framework, and makes the **learning curve neglectable**.

## Status

In [manual testing](https://twobirds.gitlab.io/microcomponents/test/test.html) ( also a speed test). I am working on the documentation.

## General

This repository exports 4 independent functionalities:

1. **[Micro Components](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/MC.md?ref_type=heads)** contains the **MC** and **DC** classes you can use as super classes.


2. **[Elements](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/elements.md?ref_type=heads)** lets you define and use your own native web components. Uses (1). 
  - [Basic Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/elements.md?ref_type=heads#create-a-custom-element). 
  - [Live Example](https://twobirds.gitlab.io/microcomponents/test/test.html)
3. **[Observables](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/observables.md?ref_type=heads)** add **observability** and **run time type safety** to object properties. Also they provide **1-way binding** to placeholders in your template HTML. 
  - [Basic Usage](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/observables.md?ref_type=heads#example)
  - [Live Example](https://twobirds.gitlab.io/microcomponents/test/test.html)
4. **[Formvalues](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/formvalues.md?ref_type=heads)** gives you **2-way binding** between a HTML form and an observable object. Uses (3). 
  - [Example Code](https://gitlab.com/twoBirds/microcomponents/-/blob/main/src/test/test/testform.ts?ref_type=heads)
  - [Live Example](https://twobirds.gitlab.io/microcomponents/test/test.html)

Also there is a bundle file that contains all of the above.

Check the [typedoc API reference](https://twobirds.gitlab.io/microcomponents/typedoc/index.html) if you want to drill into the source code.

To see what can be done, go to [additional concepts](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/magic.md?ref_type=heads) which shows what it already has been used for.

## Simple Usage Example

**Micro Components** can be added to to a DOM element like this:

before:
```HTML
<div></div>
```

code:
```typescript
// create a custom micro component class
class MyMC extends DC{

	constructor( target ){
		super( target );
	}

	helloWorld(){
		console.log( 'Hello World' );
	}

}

// get some element from the DOM
const element = document.querySelector('div')

// Add the custom micro component instance to the target element
DC.add(
	element,
	'myMC',
	new MyMC( element )
);

// Hello World
element
	._mc
	.myMC
	.helloWorld();
```

after:
```HTML
<div _mc></div>
```
The `_mc` **attribute** indicates that this **HTML element contains at least one micro component**. This is needed for the selectors.

The `_mc` **attribute** and **property** are the only interference with the DOM, so any other system should be happy to work with this.

## Distinct differences to other frameworks

There are a few potentially unique aspects of this micro components system that might differentiate it from other frameworks:

- **Pure OOP Approach**: The system explicitly positions itself as a strict object-oriented alternative to the functional approaches that dominate many modern frameworks.
- **Minimal Interference**: The system has minimal DOM interference (only adding _mc attribute and property). This makes it unusually compatible with other frameworks or libraries.
- **Hierarchical Component Traversal**: The built-in parent/child/ancestor/descendant traversal methods provide a clean way to navigate component relationships.
- **Direct DOM Integration**: Unlike virtual DOM-based frameworks, this approach works directly with the actual DOM while still providing component encapsulation.
- **Outsourcing Potential**: Your external coders do not need to access your code repository or your toolchain.

The strongest argument might be for developers who prefer OOP, want minimal framework lock-in, and need a lightweight solution that works well with existing code or other libraries.

## Contact
Feel free to contact me for any questions or inquiries:

email [Frank Thürigen](mailto:fthuerigen@gmail.com?subject=Micro%20Components)

You can [fund this](https://www.gofundme.com/f/nachhaltige-programmierung).

## Disclaimer
I decided to extract this functionality from the [twoBirds framework](https://www.npmjs.com/package/twobirds-core), because it is a useful tool in itself and it is framework agnostic. It relies solely on the standard DOM and native javascript or typescript.

Later this will be backported into twoBirds as a dependency, and twoBirds will become completely modularized on the base of MCs.

**This is a massive undertaking.** MCs are just the foundation of what I do. I am about to dump [20+ years of javascript programming](https://gitlab.com/twoBirds/microcomponents/-/blob/main/assets/documentation/magic.md?ref_type=heads#things-i-already-did-with-this-in-my-own-framework-twobirds-or-in-apps-that-i-developed-with-it) into open source libraries, so feel free to [fund this](https://www.gofundme.com/f/nachhaltige-programmierung). The better this is funded, the faster it will be done. Given enough resources, I will start a crowdfunded company that will develop a new open source ecosystem for javascript/typescript programming. By **"Open Source"** I mean **really free and open**, as **you get all my inner source code with it**. Once you understand the Micro Component principle, you are back in command of your software, no matter what MC functionality you import in your system.

Since **Micro Components** are encapsuled, off-shoring and near-shoring is no problem, and reusability is guaranteed. Your external coders do not need to access your code repository or your toolchain. They only need to understand MCs.