Merge branch 'main' of https://github.com/ZtaMDev/RoundJS

Author: ZtaMDev

README.md

@@ -8,9 +8,10 @@
   <img src="https://img.shields.io/npm/v/round-core?color=brightgreen" alt="NPM Version" />
 </p>
 
-<p align="center">
-  <em>Round is a lightweight frontend framework focused on building <b>single-page applications (SPAs)</b> with <b>fine‑grained reactivity.</b></em>
-</p>
+<h3 align="center">
+  <em><b>Round</b> is a lightweight, DOM-first framework for building SPAs with fine-grained reactivity, and fast, predictable updates powered by signals and bindables</em>
+</h3>
+
 
 <div align="center">
 
@@ -74,7 +75,7 @@ Round includes a CLI with a project initializer.
 
 ```bash
 # Install the CLI
-npm install round
+bun add round-core
 
 # Create a new app
 round init myapp
@@ -142,6 +143,15 @@ export default function Counter() {
 }
 ```
 
+### Signals Internals
+
+RoundJS utilizes a high-performance reactivity engine designed for efficiency and minimal memory overhead:
+
+- **Doubly-Linked List Dependency Tracking**: Instead of using heavy `Set` objects, RoundJS uses a linked-list of subscription nodes. This eliminates array spreads and object allocations during signal updates, providing constant-time performance for adding/removing dependencies.
+- **Global Versioning (Clock)**: Every signal write increments a global version counter. Computed signals (`derive`) track the version of their dependencies and only recompute if they are "dirty" (out of date). This ensures true lazyness and avoids redundant calculations.
+- **Automatic Batching**: Multiple signal updates within the same execution cycle are batched. Effects and DOM updates only trigger once at the end of the batch, preventing "glitches" and unnecessary re-renders.
+
+
 ### `derive(fn)`
 
 Create a computed signal that updates automatically when its dependencies change.
@@ -242,6 +252,40 @@ export function Example() {
 }
 ```
 
+## DOM binding directives
+
+Round supports two-way bindings via props:
+
+- `bind:value={someBindable}` for text-like inputs, `<textarea>`, and `<select>`.
+- `bind:checked={someBindable}` for `<input type="checkbox">` and `<input type="radio">`.
+
+Round will warn if the value is not signal-like, and will warn if you bind a plain `signal()` instead of a `bindable()`.
+
+### `bindable.object(initialObject)` and deep binding
+
+Round supports object-shaped state with ergonomic deep bindings via proxies.
+
+```jsx
+import { bindable } from 'round-core';
+
+export function Profile() {
+    const user = bindable.object({
+        profile: { bio: '' },
+        flags: { newsletter: false }
+    });
+
+    return (
+        <div>
+            <textarea bind:value={user.profile.bio} />
+            <label>
+                <input type="checkbox" bind:checked={user.flags.newsletter} />
+                Subscribe
+            </label>
+        </div>
+    );
+}
+```
+
 ### `createStore(initialState, actions)`
 
 Create a shared global state store with actions and optional persistence.
@@ -286,26 +330,31 @@ const data = store.snapshot({ reactive: false }); // Get static JSON of state
 store.set('todos', []); // Direct set
 ```
 
-### `bindable.object(initialObject)` and deep binding
+### `.validate(validator, options)`
 
-Round supports object-shaped state with ergonomic deep bindings via proxies.
+Attach validation to a signal/bindable.
+
+- Invalid writes do not update the underlying value.
+- `signal.error` is itself a signal (reactive) containing the current error message or `null`.
+- `options.validateOn` can be `'input'` (default) or `'blur'`.
+- `options.validateInitial` can trigger validation on startup.
 
 ```jsx
 import { bindable } from 'round-core';
 
-export function Profile() {
-    const user = bindable.object({
-        profile: { bio: '' },
-        flags: { newsletter: false }
-    });
+export function EmailField() {
+    const email = bindable('')
+        .validate(
+            (v) => v.includes('@') || 'Invalid email',
+            { validateOn: 'blur' }
+        );
 
     return (
         <div>
-            <textarea bind:value={user.profile.bio} />
-            <label>
-                <input type="checkbox" bind:checked={user.flags.newsletter} />
-                Subscribe
-            </label>
+            <input bind:value={email} placeholder="name@example.com" />
+            <div style={() => ({ color: email.error() ? 'crimson' : '#666' })}>
+                {email.error}
+            </div>
         </div>
     );
 }
@@ -343,45 +392,6 @@ export function MyComponent() {
 }
 ```
 
-### `.validate(validator, options)`
-
-Attach validation to a signal/bindable.
-
-- Invalid writes do not update the underlying value.
-- `signal.error` is itself a signal (reactive) containing the current error message or `null`.
-- `options.validateOn` can be `'input'` (default) or `'blur'`.
-- `options.validateInitial` can trigger validation on startup.
-
-```jsx
-import { bindable } from 'round-core';
-
-export function EmailField() {
-    const email = bindable('')
-        .validate(
-            (v) => v.includes('@') || 'Invalid email',
-            { validateOn: 'blur' }
-        );
-
-    return (
-        <div>
-            <input bind:value={email} placeholder="name@example.com" />
-            <div style={() => ({ color: email.error() ? 'crimson' : '#666' })}>
-                {email.error}
-            </div>
-        </div>
-    );
-}
-```
-
-## DOM binding directives
-
-Round supports two-way bindings via props:
-
-- `bind:value={someBindable}` for text-like inputs, `<textarea>`, and `<select>`.
-- `bind:checked={someBindable}` for `<input type="checkbox">` and `<input type="radio">`.
-
-Round will warn if the value is not signal-like, and will warn if you bind a plain `signal()` instead of a `bindable()`.
-
 ## JSX superset control flow
 
 Round extends JSX inside `.round` files with a control-flow syntax that compiles to JavaScript.
@@ -418,7 +428,7 @@ This compiles to efficient **keyed reconciliation** using the `ForKeyed` runtime
 - **Keyed (Recommended)**: By providing `key=expr`, Round maintains the identity of DOM nodes. If the list reorders, Round moves the existing nodes instead of recreating them. This preserves local state (like input focus, cursor position, or CSS animations).
 - **Unkeyed**: If no key is provided, Round simply maps over the list. Reordering the list will cause nodes to be reused based on their index, which might lead to state issues in complex lists.
 
-### `switch`
+### `switch(...)`
 
 ```jsx
 {switch(status()){
@@ -538,14 +548,6 @@ The CLI is intended for day-to-day development:
 
 Run `round -h` to see available commands.
 
-## Signals Internals
-
-RoundJS utilizes a high-performance reactivity engine designed for efficiency and minimal memory overhead:
-
-- **Doubly-Linked List Dependency Tracking**: Instead of using heavy `Set` objects, RoundJS uses a linked-list of subscription nodes. This eliminates array spreads and object allocations during signal updates, providing constant-time performance for adding/removing dependencies.
-- **Global Versioning (Clock)**: Every signal write increments a global version counter. Computed signals (`derive`) track the version of their dependencies and only recompute if they are "dirty" (out of date). This ensures true lazyness and avoids redundant calculations.
-- **Automatic Batching**: Multiple signal updates within the same execution cycle are batched. Effects and DOM updates only trigger once at the end of the batch, preventing "glitches" and unnecessary re-renders.
-
 ## Performance
 
 RoundJS sits in a powerful "middle ground" of performance: