onelaraveljs 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# onelaraveljs
+
+The Core JavaScript Framework for OneLaravel applications. This library provides the fundamental runtime, view management, and routing capabilities for building OneLaravel SPAs.
+
+## Installation
+
+```bash
+npm install onelaraveljs
+```
+
+## Usage
+
+OneJS is designed to be the "engine" while your application provides the "map" (Views and Configuration).
+
+### 1. Project Structure
+
+Ensure your project has the following recommended structure for frontend assets:
+```
+resources/js/
+├── app.js                        # Main entry point
+├── config/
+│   └── viewRegistry.generated.js # (Generated by build tools)
+└── views/                        # Your specific application views
+```
+
+### 2. Main Entry (`app.js`)
+
+In your project's main JavaScript entry point, you need to wire up the Core with your Project's views:
+
+```javascript
+import { App, viewLoader } from 'onelaraveljs';
+import { viewRegistry } from './config/viewRegistry.generated.js';
+
+// 1. Dependency Injection: Tell the Core where to find your views
+viewLoader.setRegistry(viewRegistry);
+
+// 2. Initialize the App
+// The App will look for window.APP_CONFIGS (injected by Laravel Blade) to configure itself
+if (window.APP_CONFIGS) {
+    App.init();
+}
+
+// 3. Export for UMD/Debugging (Optional)
+window.App = App;
+```
+
+### 3. Server-Side Setup (Blade)
+
+Ensure your main layout file injects the configuration:
+
+```html
+<script>
+    window.APP_CONFIGS = {
+        env: { ... },
+        routes: [ ... ],
+        // ... other configurations
+    };
+</script>
+<script src="{{ mix('js/app.js') }}"></script>
+```
+
+## Core Concepts
+
+### ViewLoader vs ViewRegistry
+
+- **ViewLoader** (Library): The logic responsible for dynamically importing and caching views. It is "blind" until it receives a registry.
+- **ViewRegistry** (Project): A map of view names (e.g., `'auth.login'`) to dynamic import functions. This is typically auto-generated by your build tools.
+
+### Event Service
+
+OneJS comes with a built-in Event Service for cross-component communication:
+
+```javascript
+import { App } from '@onelaravel/onejs';
+
+// Listen
+App.Event.on('user:logged-in', (user) => {
+    console.log(user);
+});
+
+// Emit
+App.Event.emit('user:logged-in', { id: 1, name: 'John' });
+```
+
+## License
+
+MIT

package/docs/integration_analysis.md

@@ -0,0 +1,116 @@
+# Tương Tác Giữa ViewManager, View và ViewControllerOptimized
+
+Tài liệu này giải thích cách `ViewControllerOptimized` sẽ thay thế `ViewController` hiện tại mà không làm gãy cấu trúc `View` và `ViewManager` của OneJS.
+
+## 1. Mối Quan Hệ Hiện Tại
+
+```mermaid
+graph TD
+    ViewManager --> |quản lý| View
+    View --> |sở hữu (composition)| ViewController
+    ViewController --> |sở hữu| Managers(EventManager, ReactiveManager...)
+```
+
+- **ViewManager**: Gọi `new View(name, data)` để tạo view mới.
+- **View**: Trong `constructor()`, nó khởi tạo `this.__ = new ViewController(path, this, null)`.
+- **ViewController**: Là "bộ não" xử lý mọi logic render, state, event.
+
+## 2. Chiến Lược Thay Thế Trong Suốt (Transparent Replacement)
+
+Chúng ta sẽ thay thế class `ViewController` cũ bằng `ViewControllerOptimized` (được đổi tên thành `ViewController` khi release) sao cho `View` và `ViewManager` **không hề hay biết** về sự thay đổi này.
+
+### Điều Kiện Cần
+
+`ViewControllerOptimized` phải implement (hoặc bridge) toàn bộ **Public API** mà `View` đang gọi đến.
+
+### Các "Điểm Chạm" (Touch Points) Chính
+
+#### A. Khởi Tạo (Trong `View.js`)
+
+```javascript
+// core/View.js
+import { ViewController } from "./ViewController.js"; // <-- Sau này sẽ trỏ tới file mới
+
+export class View {
+  constructor(path, config) {
+    // ...
+    // Logic này giữ nguyên, chỉ cần đảm bảo ViewController mới nhận đúng tham số
+    const controller = new ViewController(path, this, null);
+    // ...
+  }
+}
+```
+
+#### B. Setup & Config (Trong `ViewManager.js` & `View.js`)
+
+`View` gọi `this.__.setup(config)`.
+
+- **Cũ**: `ViewController.setup()` gọi `InitializationManager` (hoặc logic hỗn hợp).
+- **Mới**: `ViewControllerOptimized.setup()` sẽ gọi `ConfigHelper.process(this, config)`.
+
+#### C. Rendering (Trong `ViewManager.js`)
+
+`ViewManager` gọi `view.__.render()` hoặc `virtualRender()`.
+
+- **Cũ**: `this._renderEngine.render()`.
+- **Mới**: `RenderHelper.render(this)`.
+
+#### D. Hydration (SSR) (Trong `ViewManager.js`)
+
+`ViewManager` gọi `view.__.__scan(ssrData)`.
+
+- **Cũ**: Logic scan nằm trong `RenderEngine` hoặc inline.
+- **Mới**: `scanRenderedView` gọi `RenderHelper.scan(this, ssrData)`.
+
+#### E. State & Props Access (Trong Compiled View Files)
+
+Các file view đã compile (như `WebTemplatesExamplesSectionsDebtItem.js`) truy cập `this` (là instance của `View`), và `View` proxy sang `ViewController`.
+
+```javascript
+// Ví dụ compiled code
+render() {
+    return `... ${this.__reactive(id, keys, ...)} ...`;
+}
+```
+
+- **Yêu cầu**: `ViewControllerOptimized` **BẮT BUỘC** phải có phương thức `__reactive`.
+- **Implementation**:
+  ```javascript
+  __reactive(id, keys, renderFn) {
+      // Forward sang Helper
+      return ReactiveHelper.renderOutputComponent(this, keys, renderFn);
+  }
+  ```
+
+## 3. Bản Đồ API (API Mapping)
+
+Dưới đây là mapping chi tiết các method mà `View` gọi sang `ViewController`:
+
+| View Method (Caller) | ViewController (Old)        | ViewControllerOptimized (New) | Helper                                  |
+| :------------------- | :-------------------------- | :---------------------------- | :-------------------------------------- |
+| `setup(config)`      | `setup(config)`             | `setup(config)`               | `ConfigHelper`                          |
+| `render()`           | `_renderEngine.render()`    | `render()`                    | `RenderHelper`                          |
+| `prerender()`        | `_renderEngine.prerender()` | `prerender()`                 | `RenderHelper`                          |
+| `destroy()`          | `destroy()`                 | `destroy()`                   | Gọi `LifecycleHelper`, `EventHelper`... |
+| `.states` (Getter)   | `this.states`               | `this.states`                 | _Giữ nguyên (ViewState)_                |
+| `.id` (Getter)       | `this.id`                   | `this.id`                     | _Property trực tiếp_                    |
+| `__reactive()`       | _(via RenderEngine/Mixin)_  | `__reactive()`                | `ReactiveHelper`                        |
+| `addEventConfig()`   | Use `_eventManager`         | `addEventConfig()`            | `EventHelper` / `this.events` (data)    |
+
+## 4. Kế Hoạch Thay Thế (Release Plan)
+
+1.  **Giai đoạn 1 (Hiện tại)**:
+    - Hoàn thiện `ViewControllerOptimized` và các `Helper`.
+    - Đảm bảo `ViewControllerOptimized` chạy song song và pass unit test/manual test.
+2.  **Giai đoạn 2 (Switch)**:
+
+    - Đổi tên `ViewController.js` -> `ViewControllerLegacy.js`.
+    - Đổi tên `ViewControllerOptimized.js` -> `ViewController.js`.
+
+3.  **Giai đoạn 3 (Integration Test)**:
+    - Chạy thử `ViewManager` với Controller mới.
+    - Vì `ViewManager` và `View` chỉ import `ViewController` theo đường dẫn file `core/ViewController.js`, việc đổi tên file là đủ để tích hợp.
+
+## 5. Kết Luận
+
+`ViewManager` và `View` **không cần sửa đổi code**. Chúng tương tác với Controller thông qua một Interface ngầm định (duck typing). Miễn là `ViewControllerOptimized` implement đủ các method public (như `render`, `setup`, `destroy`, `__reactive`), hệ thống sẽ hoạt động bình thường với hiệu suất cao hơn.

package/docs/onejs_analysis.md

@@ -0,0 +1,108 @@
+# Phân Tích Framework OneJS
+
+Tài liệu này tổng hợp phân tích về cấu trúc và cơ chế hoạt động của **OneJS**, một framework frontend custom được thiết kế để hoạt động chặt chẽ với Laravel Blade (dựa trên cấu trúc file và cách sinh code).
+
+## 1. Tổng Quan
+
+OneJS là một Single Page Application (SPA) framework tự xây dựng, có khả năng:
+
+- **Client-side Rendering (CSR)**: Render giao diện động tại phía client.
+- **Server-side Rendering (SSR) Hydration**: Có khả năng "scan" và "hydrate" HTML được render sẵn từ server (Laravel Blade) để gắn logic Javascript vào.
+- **Component-based**: Tổ chức code theo các View/Component độc lập.
+- **Reactivity**: Hệ thống state management reactive tự xây dựng.
+
+## 2. Cấu Trúc Thư Mục (`resources/js/onejs`)
+
+- **`core/`**: Chứa mã nguồn cốt lõi của framework.
+  - `ViewManager.js`: Quản lý toàn bộ hệ thống view, routing và điều phối.
+  - `ViewController.js`: Controller cho từng instance của view, quản lý lifecycle, state, và events.
+  - `managers/`: Các module con hỗ trợ `ViewController` (như `RenderEngine`, `EventManager`, `ReactiveManager`).
+  - `OneMarkup.js`: Công cụ thao tác DOM và parse cấu trúc markup.
+  - `Router.js`: Xử lý điều hướng client-side.
+- **`views/`**: Chứa các file Javascript được biên dịch (compiled) từ các file gốc (có thể là Blade component). Đây là nơi chứa logic cụ thể của từng view.
+- **`app.js` & `init.js`**: Điểm khởi chạy của ứng dụng.
+
+## 3. Kiến Trúc Cốt Lõi
+
+### A. ViewManager (`core/ViewManager.js`)
+
+Đây là "bộ não" của ứng dụng:
+
+- **Quản lý View**: Lưu trữ cache các view template (`templates`, `cachedViews`).
+- **Loading**: Hỗ trợ Dynamic Import view thông qua `ViewLoader`.
+- **Routing**: Tích hợp với `Router` để load view dựa trên URL.
+- **Render & Scan**: Cung cấp 2 phương thức chính:
+  - `loadView()`: Load và render mới một view (CSR).
+  - `scanView()`: Scan DOM hiện tại (được server render) để gắn logic JS vào (SSR Hydration).
+- **Super View**: Hỗ trợ khái niệm "Layout" (Super View) cho phép lồng các view con vào view cha.
+
+### B. ViewController (`core/ViewController.js`)
+
+Mỗi view instance sẽ có một `ViewController` riêng biệt:
+
+- **Lifecycle Management**: Quản lý các hooks như `created`, `mounted`, `destroyed` thông qua `LifecycleManager`.
+- **Managers**: Nó ủy quyền các tác vụ cụ thể cho các manager con:
+  - `RenderEngine`: Xử lý render HTML.
+  - `EventManager`: Đăng ký và xử lý sự kiện DOM.
+  - `ReactiveManager`: Theo dõi thay đổi state và cập nhật UI.
+  - `ResourceManager`: Quản lý CSS/JS assets riêng của view.
+
+### C. RenderEngine (`core/managers/RenderEngine.js`)
+
+Chịu trách nhiệm sinh ra HTML hoặc cập nhật DOM:
+
+- **Render**: Chạy hàm `render()` của view để tạo ra chuỗi HTML.
+- **Scan**: Duyệt qua cấu trúc DOM thực tế để tìm các element tương ứng với logic của view (`scanDOMElements`).
+- **Virtual Render**: Chế độ render ảo để tính toán cấu trúc mà không update DOM ngay lập tức.
+- **Wrapper**: Hỗ trợ bọc view trong các thẻ container (wrapper) để quản lý phạm vi.
+
+### D. Hệ Thống Reactivity (`core/ViewState.js` & `views/...js`)
+
+Logic reactive hoạt động như sau:
+
+1. **Khai báo State**: Trong file view biên dịch, các state được đăng ký qua `__STATE__.__.register()`.
+2. **Setters**: Tạo ra các hàm setter (ví dụ `setDebtData`).
+3. **Binding**: Trong hàm `render`, các cấu trúc như `this.__reactive` hoặc `this.__classBinding` được sử dụng để gắn kết dữ liệu với DOM.
+4. **Update**: Khi state thay đổi qua setter, `ReactiveManager` sẽ kích hoạt cập nhật lại các phần DOM bị ảnh hưởng (fine-grained updates).
+
+## 4. Luồng Hoạt Động (Data Flow)
+
+### Khởi tạo App
+
+1. `init.js` kiểm tra config `window.APP_CONFIGS`.
+2. Khởi tạo `OneMarkup`, `Router`, `ViewManager`.
+3. Nếu là SSR, gọi `Router.start(true)` và hệ thống sẽ thực hiện `scanView` thay vì render mới.
+
+### Quy trình Render một View (CSR)
+
+1. `ViewManager.loadView(name)` được gọi.
+2. Load module view từ `views/`.
+3. Tạo instance `ViewEngine` (wrapper của `ViewController`).
+4. Chạy `RenderEngine.render` -> Sinh HTML string.
+5. Insert HTML vào container (`#app-root`).
+6. Gọi hook `mounted`.
+
+### Quy trình Hydrate một View (SSR)
+
+1. `ViewManager.scanView(name)` được gọi.
+2. Tìm kiếm dữ liệu `ssrData` đã được server inject.
+3. Tạo instance View.
+4. `RenderEngine.scan` -> Tìm các element trong DOM tương ứng với View ID.
+5. Gắn các event handlers và binding mà không render lại HTML.
+
+## 5. Phân Tích File View (`views/WebTemplatesExamplesSectionsDebtItem.js`)
+
+File view được biên dịch chứa:
+
+- **Hàm khởi tạo**: Nhận `App`, `systemData`, `$$$DATA$$$` (props).
+- **State Setup**: `useState`, `setDebtData`...
+- **Methods**: Các hàm xử lý logic (ví dụ `togglePaidStatus`, `handleUpdateDebt`).
+- **Render Function**: Trả về chuỗi HTML template string, sử dụng các helper:
+  - `${this.__classBinding(...)}`: Binding class động.
+  - `${this.__addEventConfig(...)}`: Gắn sự kiện (click, submit...).
+  - `${this.__reactive(...)}`: Hiển thị dữ liệu text động.
+  - `${this.__watch(...)}`: Render lại khối HTML khi state phụ thuộc thay đổi.
+
+## Kết luận
+
+OneJS là một framework khá phức tạp và mạnh mẽ, được thiết kế tối ưu cho việc kết hợp giữa Server-side Rendering của Laravel và tính năng động của SPA. Nó tự quản lý DOM, Event và State mà không phụ thuộc vào các thư viện lớn như React hay Vue, giúp tối ưu hóa tải trọng và kiểm soát chi tiết quá trình render.