round-core 0.0.3 → 0.0.5

package/.github/workflows/benchmarks.yml

@@ -0,0 +1,44 @@
+name: Framework Benchmarks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v1
+      with:
+        bun-version: latest
+
+    - name: Install Root Dependencies
+      run: bun install
+
+    - name: Build Round Core
+      run: bun run build:core
+
+    - name: Install Benchmark Dependencies
+      working-directory: ./benchmarks
+      run: bun install
+
+    - name: Run Build Benchmarks
+      working-directory: ./benchmarks
+      run: bun run bench:build
+
+    - name: Run Runtime Benchmarks
+      working-directory: ./benchmarks
+      run: bun run bench:runtime
+
+    - name: Upload Report
+      uses: actions/upload-artifact@v4
+      with:
+        name: benchmark-report
+        path: benchmarks/reports/build-bench.json

package/README.md

@@ -1,11 +1,11 @@
 <h1 align="center">Round Framework</h1>
  
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ZtaMDev/RoundJS/main/Round.png" alt="Dars Framework Logo" width="200" />
+  <img src="https://raw.githubusercontent.com/ZtaMDev/RoundJS/main/Round.png" alt="Round Framework Logo" width="200" />
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/round-core?color=brightgreen" alt="PyPI Version" />
+  <img src="https://img.shields.io/npm/v/round-core?color=brightgreen" alt="NPM Version" />
 </p>
 
 <p align="center">
@@ -26,6 +26,16 @@ Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates d
 - **A JSX superset**: `.round` files support extra control-flow syntax that compiles to JavaScript.
 - **Minimal runtime**: DOM-first runtime (no VDOM diffing).
 
+## Architecture
+
+Round is a **No-VDOM** framework.
+
+1.  **Direct DOM Manipulation**: Components run once. They return real DOM nodes (via `document.createElement`).
+2.  **Fine-Grained Reactivity**: Use of `signal`, `effect`, and `bindable` creates a dependency graph.
+3.  **Surgical Updates**: When a signal changes, only the specific text node, attribute, or property subscribed to that signal is updated. The component function does not re-run.
+
+This avoids the overhead of Virtual DOM diffing and reconciliation entirely.
+
 ## Concepts
 
 ### SPA
@@ -89,7 +99,7 @@ Example `src/app.round`:
 
 ```jsx
 import { Route } from 'round-core';
-import { Counter } from './counter';
+import { Counter } from './counter.round';
 
 export default function App() {
     return (
@@ -115,23 +125,41 @@ Create a reactive signal.
 ```jsx
 import { signal } from 'round-core';
 
-export function Counter() {
+export default function Counter() {
     const count = signal(0);
 
     return (
         <div>
             <h1>Count: {count()}</h1>
-            <button onClick={() => count(count() + 1)}>Increment</button>
+            <div style={{ display: 'flex', gap: '8px' }}>
+                <button onClick={() => count(count() + 1)}>Increment</button>
+                <button onClick={() => count(count() - 1)}>Decrement</button>
+            </div>
         </div>
     );
 }
 ```
 
+### `derive(fn)`
+
+Create a computed signal that updates automatically when its dependencies change.
+
+```javascript
+import { signal, derive } from 'round-core';
+
+const count = signal(1);
+const double = derive(() => count() * 2);
+
+console.log(double()); // 2
+count(5);
+console.log(double()); // 10
+```
+
 ### `effect(fn)`
 
 Run `fn` whenever the signals it reads change.
 
-```js
+```javascript
 import { signal, effect } from 'round-core';
 
 const name = signal('Ada');
@@ -162,6 +190,40 @@ export function Example() {
 }
 ```
 
+### `createStore(initialState, actions)`
+
+Create a shared global state store with actions and optional persistence.
+
+```javascript
+import { createStore } from 'round-core';
+
+// 1. Define Store
+const store = createStore({
+    todos: [],
+    filter: 'all'
+}, {
+    addTodo: (state, text) => ({ 
+        ...state, 
+        todos: [...state.todos, { text, done: false }] 
+    })
+});
+
+// 2. Use in Component
+export function TodoList() {
+    const todos = store.use('todos'); // Returns a bindable signal
+    
+    return (
+        <div>
+            {todos().map(todo => <div>{todo.text}</div>)}
+            <button onClick={() => store.addTodo('Buy Milk')}>Add</button>
+        </div>
+    );
+}
+
+// 3. Persistence (Optional)
+store.persist('my-app-store'); 
+```
+
 ### `bindable.object(initialObject)` and deep binding
 
 Round supports object-shaped state with ergonomic deep bindings via proxies.
@@ -187,37 +249,6 @@ export function Profile() {
 }
 ```
 
-### `$pick(path)`
-
-Create a view signal from a signal/bindable that holds an object.
-
-```js
-import { bindable } from 'round-core';
-
-const user = bindable({ profile: { bio: 'Hello' } });
-const bio = user.$pick('profile.bio');
-
-console.log(bio());
-```
-
-### `.transform(fromInput, toOutput)`
-
-Transform a signal/bindable to adapt between DOM values (often strings) and your internal representation.
-
-```jsx
-import { bindable } from 'round-core';
-
-export function AgeField() {
-    const age = bindable('18')
-        .transform(
-            (str) => Math.max(0, parseInt(str, 10) || 0),
-            (num) => String(num)
-        );
-
-    return <input type="number" bind:value={age} />;
-}
-```
-
 ### `.validate(validator, options)`
 
 Attach validation to a signal/bindable.
@@ -277,6 +308,7 @@ Notes:
 
 - Conditions may be normal JS expressions.
 - For *simple paths* like `flags.showCounter` (identifier/member paths), Round will auto-unwrap signal-like values (call them) so the condition behaves as expected.
+- Multiple elements inside a block are automatically wrapped in a Fragment.
 
 ### `for (... in ...)`
 
@@ -288,44 +320,70 @@ Notes:
 
 This compiles roughly to a `.map(...)` under the hood.
 
-## Rendering model (no VDOM)
-
-Round renders to the DOM directly using a small runtime:
-
-- Elements are created with `document.createElement(...)`.
-- Dynamic children and reactive props are updated via `effect()` subscriptions.
-- Components are functions returning DOM nodes (or arrays of nodes).
-
-This is a **DOM-first, fine-grained reactive model**, rather than a Virtual DOM diffing renderer.
-
 ## Routing
 
-Round includes router primitives intended for SPA navigation.
+Round includes router primitives intended for SPA navigation. All route paths must start with a forward slash `/`.
 
-Typical usage:
+### Basic Usage
 
 ```jsx
-import { Route } from 'round-core';
+import { Route, Link } from 'round-core';
 
 export default function App() {
     return (
         <div>
-            <Route route="/" title="Home">
-                <div>Home</div>
+            <nav>
+                <Link href="/">Home</Link>
+                <Link href="/about">About</Link>
+            </nav>
+
+            <Route route="/" title="Home" exact>
+                <div>Welcome Home</div>
             </Route>
             <Route route="/about" title="About">
-                <div>About</div>
+                <div>About Us Content</div>
             </Route>
         </div>
     );
 }
 ```
 
+### Nested Routing and Layouts
+
+Routes can be nested to create hierarchical layouts. Child routes automatically inherit and combine paths with their parents.
+
+- **Prefix Matching**: By default, routes use prefix matching (except for the root `/`). This allows a parent route to stay rendered as a "shell" or layout while its children are visited.
+- **Exact Matching**: Use the `exact` prop to ensure a route only renders when the path matches precisely (default for root `/`).
+
+```jsx
+<Route route="/dashboard" title="Dashboard">
+    <h1>Dashboard Shell</h1>
+
+    {/* This route matches /dashboard/profile */}
+    <Route route="/dashboard/profile">
+        <h2>User Profile</h2>
+    </Route>
+
+    {/* This route matches /dashboard/settings */}
+    <Route route="/dashboard/settings">
+        <h2>Settings</h2>
+    </Route>
+</Route>
+```
+
 ## Suspense and lazy loading
 
 Round supports `Suspense` for promise-based rendering and `lazy()` for code splitting.
 
-(These APIs are evolving; expect improvements as Round’s compiler and runtime expand.)
+```jsx
+import { Suspense, lazy } from 'round-core';
+const LazyWidget = lazy(() => import('./Widget'));
+
+<Suspense fallback={<div>Loading...</div>}>
+    <LazyWidget />
+</Suspense>
+```
+
 
 ## Error handling
 

package/benchmarks/apps/react/index.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<body>
+    <div id="root"></div>
+    <script type="module" src="./main.jsx"></script>
+</body>
+
+</html>

package/benchmarks/apps/react/main.jsx

@@ -0,0 +1,25 @@
+import React, { useState, useEffect } from 'react';
+import ReactDOM from 'react-dom/client';
+
+function App() {
+    const [count, setCount] = useState(0);
+    const [items] = useState(Array.from({ length: 1000 }, (_, i) => i));
+
+    useEffect(() => {
+        console.log('React App Mounted');
+    }, []);
+
+    return (
+        <div>
+            <h1>React Benchmark</h1>
+            <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+            <ul>
+                {items.map(i => (
+                    <li key={i}>Item {i}</li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+
+ReactDOM.createRoot(document.getElementById('root')).render(<App />);

package/benchmarks/apps/react/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+    root: __dirname,
+    plugins: [react()],
+    build: {
+        outDir: '../../dist-bench/react',
+        emptyOutDir: true,
+        minify: true
+    }
+});

package/benchmarks/apps/round/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<body>
+    <div id="app"></div>
+    <script type="module">
+        import { render } from 'round-core';
+        import App from './main.jsx';
+        render(App, document.getElementById('app'));
+    </script>
+</body>
+</html>

package/benchmarks/apps/round/main.jsx

@@ -0,0 +1,22 @@
+import { createElement, signal, onMount } from 'round-core';
+
+export default function App() {
+    const count = signal(0);
+    const items = signal(Array.from({ length: 1000 }, (_, i) => i));
+
+    onMount(() => {
+        console.log('Round App Mounted');
+    });
+
+    return (
+        <div>
+            <h1>Round Benchmark</h1>
+            <button onClick={() => count(count() + 1)}>Count: {count}</button>
+            <ul>
+                {() => items().map(i => (
+                    <li key={i}>Item {i}</li>
+                ))}
+            </ul>
+        </div>
+    );
+}

package/benchmarks/apps/round/vite.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite';
+import RoundPlugin from 'round-core/vite-plugin'; // Use package export
+import path from 'path';
+
+export default defineConfig({
+    root: __dirname,
+    plugins: [
+        RoundPlugin()
+    ],
+    build: {
+        outDir: '../../dist-bench/round',
+        emptyOutDir: true,
+        minify: true
+    }
+});