Updated README.md

Author: DeepDoge

README.md

@@ -16,7 +16,7 @@
     <b>purify.js</b> is a 1.0kB <i>(minified, gzipped)</i> JavaScript UI building library that encourages the usage of pure JavaScript and DOM, while providing a thin layer of abstraction for the annoying parts for better DX <i>(developer experience)</i>. 🚀
 </p>
 
-# Features 🌟
+# Features 🌟🚀
 
 - 🔥 **Keeps you close to the DOM.**
 - ✍️ `HTMLElement` builder allows you to differentiate between attributes and properties.
@@ -33,13 +33,13 @@
 
 ---
 
-## Compare 📏
+## Compare 📏⚖️
 
-### Size ⚡
+### Size ⚡📊
 
 | Library         | .min.js | .min.js.gz |
 | --------------- | ------- | ---------- |
-| **purify.js**   | 2.3kB   | 1.0kB      |
+| **purify.js**   | 2.2kB   | 1.0kB      |
 | Preact 10.19.3  | 11.2kB  | 4.5kB      |
 | Solid 1.8.12    | 23kB    | 8.1kB      |
 | jQuery 3.7.1    | 85.1kB  | 29.7kB     |
@@ -49,7 +49,7 @@
 
 ---
 
-## Installation 🍙
+## Installation 📦🍙
 
 To install **purify.js**, follow the [jsr.io/@purifyjs/core](https://jsr.io/@purifyjs/core).
 
@@ -65,53 +65,58 @@ import { computed, Lifecycle, ref, Signal, tags } from "@purifyjs/core";
 const { div, section, button, ul, li, input } = tags;
 
 function App() {
-    return div().id("app").children(Counter());
+    return div().id("app").replaceChildren$(Counter());
 }
 
 function Counter() {
     const count = ref(0);
     const double = count.derive((count) => count * 2);
     const half = computed(() => count.val * 0.5);
 
-    return div().children(
+    return div().replaceChildren$(
         section({ class: "input" })
             .ariaLabel("Input")
-            .children(
+            .replaceChildren$(
                 button()
                     .title("Decrement by 1")
                     .onclick(() => count.val--)
                     .textContent("-"),
-                input().type("number").effect(useBindNumber(count)).step("1"),
+                input().type("number").$effect(useBindNumber(count)).step("1"),
                 button()
                     .title("Increment by 1")
                     .onclick(() => count.val++)
                     .textContent("+"),
             ),
         section({ class: "output" })
             .ariaLabel("Output")
-            .children(
-                ul().children(
-                    li().children("Count: ", count),
-                    li().children("Double: ", double),
-                    li().children("Half: ", half),
+            .replaceChildren$(
+                ul().replaceChildren$(
+                    li().replaceChildren$("Count: ", count),
+                    li().replaceChildren$("Double: ", double),
+                    li().replaceChildren$("Half: ", half),
                 ),
             ),
     );
 }
 
-function useBindNumber(state: Signal.State<number>): Lifecycle.OnConnected<HTMLInputElement> {
+function useBindNumber(
+    state: Signal.State<number>,
+): Lifecycle.OnConnected<HTMLInputElement> {
     return (element) => {
         const listener = () => (state.val = element.valueAsNumber);
         element.addEventListener("input", listener);
-        const unfollow = state.follow((value) => (element.valueAsNumber = value), true);
+        const unfollow = state.follow(
+            (value) => (element.valueAsNumber = value),
+            true,
+        );
         return () => {
             element.removeEventListener("input", listener);
             unfollow();
         };
     };
 }
 
-document.body.append(App().node);
+document.body.append(App().$node);
 ```
 
 ### ShadowRoot
@@ -122,25 +127,25 @@ import { Builder, ref, tags } from "@purifyjs/core";
 const { div, button } = tags;
 
 function App() {
-    return div().id("app").children(Counter());
+    return div().id("app").replaceChildren$(Counter());
 }
 
 function Counter() {
     const host = div();
-    const shadow = new Builder(host.node.attachShadow({ mode: "open" }));
+    const shadow = new Builder(host.$node.attachShadow({ mode: "open" }));
 
     const count = ref(0);
 
-    shadow.children(
+    shadow.replaceChildren$(
         button()
             .title("Click me!")
             .onclick(() => count.val++)
-            .children("Count:", count),
+            .replaceChildren$("Count:", count),
     );
     return host;
 }
 
-document.body.append(App().node);
+document.body.append(App().$node);
 ```
 
 ### Web Components
@@ -151,7 +156,7 @@ import { Builder, ref, tags, WithLifecycle } from "@purifyjs/core";
 const { div, button } = tags;
 
 function App() {
-    return div().id("app").children(new CounterElement());
+    return div().id("app").replaceChildren$(new CounterElement());
 }
 
 declare global {
@@ -162,7 +167,7 @@ declare global {
 
 class CounterElement extends WithLifecycle(HTMLElement) {
     static {
-        customElements.define("x-counter", this);
+        customElements.define("x-counter", CounterElement);
     }
 
     #count = ref(0);
@@ -171,23 +176,23 @@ class CounterElement extends WithLifecycle(HTMLElement) {
         super();
         const self = new Builder<CounterElement>(this);
 
-        self.children(
+        self.replaceChildren$(
             button()
                 .title("Click me!")
                 .onclick(() => this.#count.val++)
-                .children("Count:", this.#count),
+                .replaceChildren$("Count:", this.#count),
         );
     }
 }
 
-document.body.append(App().node);
+document.body.append(App().$node);
 ```
 
-## Guide 🥡
+## Guide 📖🥡
 
 Coming soon.
 
-## Why Not JSX Templating? 🍕
+## Why Not JSX Templating? 🤔🍕
 
 - **Lack of Type Safety**: An `<img>` element created with JSX cannot have the `HTMLImageElement` type because all JSX elements must return
   the same type. This causes issues if you expect a `HTMLImageElement` some where in the code but all JSX returns is `HTMLElement` or
@@ -199,30 +204,75 @@ Coming soon.
 - **Attributes vs. Properties**: In **purify.js**, I can differentiate between attributes and properties of an element while building it,
   which is not currently possible with JSX. This distinction enhances clarity and control when defining element characteristics.
 
-## Current Limitations 🦀
-
-- **Lifecycle and Reactivity**: Currently, I use Custom Elements to detect if an element is connected to the DOM. This means:
-
-  - Every element created by the `tags` proxy, are Custom Elements. But they look like normal `<div>`(s) and `<span>`(s) and etc on the
-    DevTools, because they extend the original element and use the original tag name. This way we can follow the life cycle of every
-    element. And it works amazingly.
-  - But we also have signals, which might not return an HTMLElement. So we gotta wrap signals with something in the DOM. So we can follow
-    its lifecycle and know where it starts and ends. Traditionally this is done via `Comment` `Node`(s). But there is no feasible and sync
-    way to follow a `Comment` `Node` on the DOM while also allowing direct DOM manipulation
-    ([DOM#533](https://github.com/whatwg/dom/issues/533)). So instead of `Comment` `Node`(s), I used Custom Elements with
-    `display: contents` style to wrap signal renders. This way, I can follow the lifecycle of the signal render in the DOM, and decide to
-    follow or unfollow the signal. Since signal render itself is an `Element` this approach has limitations, such as `.parent > *` selector
-    wouldn't select all children if some are inside a signal.
+JSX is not part of this library natively, but a wrapper can be made quite easily.
 
-    As another solution to this, a persistent DocumentFrament that acts similar to `Element` with `display: contents` style but also
-    intentionally skipped by query selectors would also be useful. Similar: ([DOM#739](https://github.com/whatwg/dom/issues/736))
-
-But as long as the developer is aware of this limitation or difference, it shouldn't cause any issues.
+## Limitations ⚠️🦀
 
 - Since I use extended custom elements, safari doesn't support this yet, so if you care about safari for some reasons, use
   [ungap/custom-elements](https://github.com/ungap/custom-elements) polyfill. You can follow support at
   [caniuse](https://caniuse.com/mdn-html_global_attributes_is).
 
-- Treat built in elements with `WithLifecycle` as normal built in elements, and for example don't check if an element is
-  `instanceof WithLifecycle(HTMLDivElement)`. Because this way of doing things might be changed in the future with things like
-  [WICG/webcomponents/issues/1029](https://github.com/WICG/webcomponents/issues/1029).
+## Future 🔮🦀
+
+- Right now, when a `Signal` is connected to DOM via `Builder`, we update all of the children of the `ParentNode` with
+  `ParentNode.prototype.replaceChildren()`.
+
+  This is obviously not that great, previously at `0.1.6` I was using a `<div>` element with the style `display:contents` to wrap a rendered
+  `Signal` on the DOM. This was also allowing me to follow it's lifecyle via `connectedCallback`/`disconnectedCallback` which was allowing
+  me to follow or unfollow the `Signal`, making cleanup easier.
+
+  But since we wrap it with an `HTMLElement` it was causing problems with CSS selectors, since now each `Signal` is an `HTMLElement` on the
+  DOM.
+
+  So at `0.2.0` I made it so that all children of the `ParentNode` updates when a `Signal` child changes. Tho this issue can be escaped by
+  seperating things while writing the code. Or make use of things like `.replaceChild()`. Since all support `Signal`(s) now.
+
+  But to solve the core of this issue JS needs a real `DocumentFragment` with persistent children.
+
+  This proposal might solve this issue:
+  [DOM#739 Proposal: a DocumentFragment whose nodes do not get removed once inserted](https://github.com/whatwg/dom/issues/736).
+
+  In the puroposal they purpose on making the fragment undetactable with `childNodes` or `children` which I'm against and don't like at all.
+  `DocumentFragment` should be a `ParentNode` should have it's own children, and can be `ChildNode` of other `ParentNode`. Normal hierarchy,
+  no trasparency other than CSS.
+
+  But it's a good start, but just by having a real, working as intended, `DocumentFragment` we are not done.
+
+  Which brings be to the next point.
+
+- We also need a native, sync and easy to use way to follow lifecycle of any DOM `ChildNode`, or at least all `Element` and this new
+  persistent `DocumentFragment`. Because without a lifecycle feature we can't bind a `Signal` to the DOM, start, stop/cleanup them
+  automatically.
+
+  An issue is open here [DOM#533 Make it possible to observe connected-ness of a node](https://github.com/whatwg/dom/issues/533).
+
+  Since DOM already has a sync way to follow lifecycle of custom `HTMLElement`(s). Since this is the only way, at this time we heavily relay
+  on that. Currently we use auto created Custom Elements via `tags` proxy and `WithLifecycle` `HTMLElement` mixin. And allow `Signal`
+  related things only on those elements.
+
+- If this feature above doesn't come sooner we also keep an eye of this other proposal which has more attraction:
+  [webcomponents#1029 Proposal: Custom attributes for all elements, enhancements for more complex use cases](https://github.com/WICG/webcomponents/issues/1029)
+
+  This proposal doesn't fix the issue with `DocumentFragment`(s), but improves and makes `HTMLElement` based lifecycles more modular and DX
+  friendly.
+
+  Right now, we have a mixing function called `WithLifecycle` which can be used like:
+  ```ts
+  WithLifecycle(HTMLElement); // or
+  WithLifecycle(HTMLDivElement);
+  ```
+  It adds a lifecycle function called `$effect()` to any `HTMLElement` type. Which can later be extended by a custom element like
+  ```ts
+  class MyElement extends WithLifecycle(HTMLElement)
+  ```
+  Allowing you to create your own custom `HTMLElement` type with lifecycle. the `tags` proxy also uses `WithLifecycle` in combination with
+  `Builder` internally. so when you do `tags.div()` you are actually getting a `<div is="pure-div">` with a lifecycle. _But the `[is]`
+  attribute is not visible in the DOM since this element created by JS, not HTML_.
+
+  Anyway since this method requires you to decide if something is an element with lifecycle ahead of time, and also requires use to create
+  `pure-*` variant of native HTMLElement types in order to make them have lifecycle, it's kinda a lot. It makes sense. But it's kind of a
+  lot.
+
+  So this new custom attributes proposal can let us have lifecycle on any `Element` easily by simily adding an attribute to it. And this can
+  reshape a big portion of this codebase. And would make things connected to lifecyle of the `Element` more visible in the DOM. Which is
+  great.

apps/vite/src/examples/web-component-example.ts

@@ -13,7 +13,9 @@ declare global {
 }
 
 class CounterElement extends WithLifecycle(HTMLElement) {
-    static _ = customElements.define("x-counter", CounterElement);
+    static {
+        customElements.define("x-counter", CounterElement);
+    }
 
     #count = ref(0);