onelaraveljs 1.1.1 → 1.1.4

package/README.md

@@ -1,87 +1,182 @@
-# onelaraveljs
+# OneLaravelJS Framework
 
-The Core JavaScript Framework for OneLaravel applications. This library provides the fundamental runtime, view management, and routing capabilities for building OneLaravel SPAs.
+**OneLaravelJS** là thư viện lõi JavaScript dành cho các ứng dụng OneLaravel. Nó cung cấp nền tảng runtime, quản lý view, routing và khả năng tương tác hai chiều mạnh mẽ giữa Laravel Blade và JavaScript.
 
-## Installation
+Thư viện này đóng vai trò là "Engine", trong khi ứng dụng Laravel của bạn cung cấp "Map" (Views và Cấu hình).
+
+---
+
+## 🏗 Cài đặt
+
+Cài đặt thư viện thông qua npm:
 
 ```bash
 npm install onelaraveljs
 ```
 
-## Usage
+Sau khi cài đặt, bạn sẽ có quyền truy cập vào:
+- **Runtime Library**: Các file JS để chạy ứng dụng.
+- **CLI Tools**: Công cụ `onejs-build` để biên dịch Blade template thành JavaScript modules.
+
+---
 
-OneJS is designed to be the "engine" while your application provides the "map" (Views and Configuration).
+## 📂 Cấu trúc dự án khuyến nghị
 
-### 1. Project Structure
+Để OneLaravelJS hoạt động hiệu quả, dự án của bạn nên tuân thủ cấu trúc sau:
 
-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
+my-laravel-project/
+├── build.config.json           # File cấu hình build (BẮT BUỘC)
+├── package.json
+├── resources/
+│   ├── js/
+│   │   ├── app.js              # Entry point chính
+│   │   ├── build/              # Output của Webpack (Bundle)
+│   │   ├── config/             # Output của Compiler (Registry maps)
+│   │   ├── core/               # Output của Compiler (Proxy files)
+│   │   └── views/              # Output của Compiler (Compiled View Components)
+│   └── views/
+│       ├── _system/            # System views required by Framework
+│       └── web/                # User views
+```
+
+---
+
+## ⚙️ Cấu hình (`build.config.json`)
+
+Tạo file `build.config.json` tại thư mục gốc dự án để định nghĩa các ngữ cảnh (contexts) build:
+
+```json
+{
+    "contexts": {
+        "web": {
+            "sources": [
+                "resources/views/_system",
+                "resources/views/web"
+            ],
+            "output": {
+                "views": "resources/js/views/web",
+                "register": "resources/js/config/templates.web.js",
+                "bundle": "resources/js/build/web.bundle.js"
+            },
+            "dist": {
+                "bundle": "public/static/web/js/main.bundle.js",
+                "css": "public/static/web/css",
+                "assets": "public/static/web/assets"
+            }
+        }
+    }
+}
+```
+
+---
+
+## 🛠 Công cụ CLI (`onejs-build`)
+
+OneLaravelJS đi kèm với trình biên dịch mạnh mẽ để chuyển đổi Blade Templates thành JavaScript Components.
+
+### Các lệnh phổ biến:
+
+Thêm vào `package.json` của bạn:
+
+```json
+"scripts": {
+    "build:templates": "onejs-build all",
+    "build:templates:web": "onejs-build web",
+    "dev:blade": "onejs-build"
+}
 ```
 
-### 2. Main Entry (`app.js`)
+- **`onejs-build all`**: Biên dịch tất cả các context được định nghĩa trong `build.config.json`.
+- **`onejs-build web`**: Chỉ biên dịch context `web`.
+- **`onejs-build`**: Chạy chế độ Interactive (Menu chọn).
 
-In your project's main JavaScript entry point, you need to wire up the Core with your Project's views:
+### Cơ chế hoạt động:
+1.  Đọc `build.config.json`.
+2.  Quét các file `.blade.php` trong thư mục `sources`.
+3.  Phân tích cú pháp Blade, Directives (@if, @foreach), và OneJS directives (x-data, x-bind).
+4.  Sinh ra các file ES6 Module tại thư mục `output.views`.
+5.  Tạo file Registry (`templates.web.js`) để map tên view sang file JS.
+
+---
+
+## 🚀 Sử dụng trong ứng dụng (`app.js`)
+
+Tại `resources/js/app.js`, bạn cần kết nối Core Framework với Registry views đã được biên dịch:
 
 ```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);
+// Import Registry đã được CLI sinh ra (thông qua Proxy hoặc trực tiếp)
+// Lưu ý: ViewTemplates thường được export từ file generated resources/js/core/ViewTemplate.js
+import { ViewTemplates } from './core/ViewTemplate.js'; 
+
+// 1. Dependency Injection: Nạp danh sách views vào Core
+viewLoader.setRegistry(ViewTemplates);
 
-// 2. Initialize the App
-// The App will look for window.APP_CONFIGS (injected by Laravel Blade) to configure itself
+// 2. Khởi tạo App
+// App sẽ tự động đọc window.APP_CONFIGS từ Blade để cấu hình Env, Routes...
 if (window.APP_CONFIGS) {
     App.init();
 }
 
-// 3. Export for UMD/Debugging (Optional)
+// 3. Export global (Tùy chọn, dùng cho debug hoặc legacy scripts)
 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
+## 🧠 Core Concepts
 
-- **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.
+### 1. View System
+OneJS coi mỗi file Blade là một Component.
+- **Server**: Render HTML tĩnh (SEO).
+- **Client**: Hydrate HTML đó thành Interactive Component.
 
-### Event Service
+### 2. ViewLoader & Registry
+- **ViewLoader**: Là "bộ não" tải view lười (lazy-load). Nó không biết gì về ứng dụng của bạn cho đến khi được cung cấp Registry.
+- **ViewRegistry**: Là "cuốn danh bạ" map tên view (`web.home`) tới file code (`WebHome.js`). File này được sinh tự động.
 
-OneJS comes with a built-in Event Service for cross-component communication:
+### 3. Event Service
+Hệ thống Event Bus tích hợp sẵn:
 
 ```javascript
 import { App } from 'onelaraveljs';
 
-// Listen
-App.Event.on('user:logged-in', (user) => {
-    console.log(user);
+// Lắng nghe
+App.Event.on('cart:updated', (data) => {
+    console.log('Cart count:', data.count);
 });
 
-// Emit
-App.Event.emit('user:logged-in', { id: 1, name: 'John' });
+// Phát sự kiện
+App.Event.emit('cart:updated', { count: 5 });
 ```
 
+---
+
+## 🤝 Đóng góp & Phát triển (Development)
+
+Nếu bạn muốn chỉnh sửa source code của chính thư viện `onelaraveljs`:
+
+### Cấu trúc Source:
+- `bin/`: Chứa file thực thi CLI.
+- `scripts/`: Chứa logic biên dịch (Python/Node).
+  - `build.py`: Script chính điều phối build.
+  - `compiler/`: Bộ biên dịch Blade sang JS (Python).
+- `src/`: Source code JS runtime.
+  - `core/`: Logic cốt lõi (Router, ViewEngine...).
+
+### Quy trình phát triển:
+1.  Clone repo về máy.
+2.  Chạy `npm install`.
+3.  Symlink sang dự án test (`npm link` hoặc chỉnh sửa trực tiếp trong `node_modules` để debug nhanh).
+4.  Đảm bảo biến môi trường `ONEJS_PROJECT_ROOT` được xử lý đúng trong các script build nếu chạy thủ công.
+
+### Testing:
+Kiểm tra các thay đổi bằng cách chạy build trên một dự án Laravel thực tế sử dụng thư viện này (ví dụ `onelaravel`).
+
+---
+
 ## License
 
-MIT
+MIT License.

package/index.js

@@ -3,13 +3,15 @@ import { App } from './src/app.js';
 import { viewLoader } from './src/core/ViewLoader.js';
 import { EventService } from './src/core/services/EventService.js';
 import initApp from './src/init.js';
+import { View } from './src/core/View.js';
 
 // Export Core Components
 export { 
     App, 
     viewLoader,
     EventService,
-    initApp 
+    initApp,
+    View
 };
 
 // Default export

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onelaraveljs",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "OneLaravel JS Framework Core & Compiler",
   "main": "index.js",
   "bin": {

package/scripts/build.py

@@ -221,7 +221,7 @@ def build_view_template_importer(created_files, output_path, context='all'):
     
     if build_config and context != 'all' and context in build_config['contexts']:
         # Use context-specific registry file
-        output_path = os.path.join(Path(__file__).parent.parent, build_config['contexts'][context]['output']['register'])
+        output_path = os.path.join(config.project_root, build_config['contexts'][context]['output']['register'])
     
     # Create output directory if it doesn't exist
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
@@ -385,8 +385,9 @@ def build_main_spa_file():
 
 def load_build_config():
     """Load build.config.json"""
-    config_path = Path(__file__).parent.parent / 'build.config.json'
-    if not config_path.exists():
+    # Use the config object to find the project root
+    config_path = os.path.join(config.project_root, 'build.config.json')
+    if not os.path.exists(config_path):
         return None
     
     with open(config_path, 'r', encoding='utf-8') as f:
@@ -417,15 +418,15 @@ def get_source_directories(context_name=None):
         # Return sources for specific context
         sources = build_config['contexts'][context_name]['sources']
         # Convert relative paths to absolute
-        base_path = Path(__file__).parent.parent
-        return [str(base_path / src) for src in sources]
+        base_path = config.project_root
+        return [os.path.join(base_path, src) for src in sources]
     elif build_config and context_name == 'all':
         # Return all sources from all contexts
-        base_path = Path(__file__).parent.parent
+        base_path = config.project_root
         all_sources = set()
         for ctx in build_config['contexts'].values():
             for src in ctx['sources']:
-                all_sources.add(str(base_path / src))
+                all_sources.add(os.path.join(base_path, src))
         return list(all_sources)
     else:
         # Fallback to config.get_build_directories()
@@ -537,7 +538,7 @@ def main():
                     # Create a proxy ViewTemplate.js in core/ that re-exports from context registry
                     core_template_path = os.path.join(config.js_input_path, 'core', 'ViewTemplate.js')
                     relative_to_registry = os.path.relpath(
-                        os.path.join(Path(__file__).parent.parent, registry_path),
+                        os.path.join(config.project_root, registry_path),
                         os.path.dirname(core_template_path)
                     ).replace('\\', '/')
                     

package/scripts/compiler/main_compiler.py

@@ -1005,7 +1005,7 @@ class BladeCompiler:
         # Add View import if scripts are registered
         view_import = ""
         if script_registrations:
-            view_import = "import { View } from '../core/View.js';\n\n"
+            view_import = "import { View } from 'onelaraveljs';\n\n"
         
         return_template = setup_script_line + view_import + script_registrations_line + """export function """ + function_name + """($$$DATA$$$ = {}, systemData = {}) {
     const {App, View, __base__, __layout__, __page__, __component__, __template__, __context__, __partial__, __system__, __env = {}, __helper = {}} = systemData;

package/scripts/dev-context.js

@@ -27,7 +27,8 @@ if (!['web', 'admin'].includes(context)) {
 }
 
 // Load build config
-const buildConfigPath = path.resolve(__dirname, '../build.config.json');
+const projectRoot = process.env.ONEJS_PROJECT_ROOT || process.cwd();
+const buildConfigPath = path.resolve(projectRoot, 'build.config.json');
 const buildConfig = JSON.parse(readFileSync(buildConfigPath, 'utf-8'));
 const contextConfig = buildConfig.contexts[context];
 
@@ -40,9 +41,11 @@ const config = {
     context: context,
     watchPaths: {
         blade: contextConfig.sources, // Array of blade source paths from config
-        jsCore: 'resources/js/onejs', // Watch entire onejs directory
-        jsViewsExclude: 'resources/js/onejs/views', // Exclude views directory
-        compiler: 'scripts/compiler'
+        jsCore: 'resources/js', // Watch entire js directory
+        jsViewsExclude: 'resources/js/views', // Exclude views directory
+        jsBuildExclude: 'resources/js/build',
+        jsConfigExclude: 'resources/js/config',
+        compiler: 'node_modules/onelaraveljs/scripts/compiler'
     },
     buildCommand: `npm run build:${context}`,
     phpServeCommand: 'php artisan serve',

package/scripts/generate-assets-order.js

@@ -13,23 +13,31 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// Load build.config.json to get context paths
-const buildConfig = JSON.parse(fs.readFileSync(path.join(__dirname, '../build.config.json'), 'utf-8'));
+// Load build.config.json from project root
+const projectRoot = process.env.ONEJS_PROJECT_ROOT || process.cwd();
+const configPath = path.join(projectRoot, 'build.config.json');
+
+try {
+    var buildConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+} catch (e) {
+    console.error(`Error loading build.config.json from ${configPath}:`, e.message);
+    process.exit(1);
+}
 
 // Get context from environment variable
 const buildContext = process.env.BUILD_CONTEXT || 'web';
 
 // Determine static path based on context
 const STATIC_PATH = buildConfig.contexts[buildContext] 
-    ? path.join(__dirname, '..', path.dirname(buildConfig.contexts[buildContext].dist.bundle))
-    : path.join(__dirname, '../public/static/app');
+    ? path.join(projectRoot, path.dirname(buildConfig.contexts[buildContext].dist.bundle))
+    : path.join(projectRoot, 'public/static/app');
 
 // Determine base URL path for assets
 const BASE_URL = buildConfig.contexts[buildContext]
     ? `/static/${buildContext}/js/`
     : '/static/app/';
 
-const OUTPUT_FILE = path.join(__dirname, '../resources/views/partials/assets-scripts.blade.php');
+const OUTPUT_FILE = path.join(projectRoot, 'resources/views/partials/assets-scripts.blade.php');
 
 function getAssetsByCategory() {
     const assets = {

package/src/core/ViewManager.js

@@ -1,5 +1,5 @@
 import { SEOTagConfig } from './SEOConfig.js';
-import { ViewTemplates } from './ViewTemplate.js';
+// ViewTemplates import removed
 import { hasData, uniqId } from '../helpers/utils.js';
 import { View, ViewEngine } from './View.js';
 import { ViewState } from './ViewState.js';
@@ -126,7 +126,7 @@ export class ViewManager {
         /**
          * @type {Object<string, ViewEngine>}
          */
-        this.templates = ViewTemplates;
+        this.templates = viewLoader.registry || {};
         /**
          * @type {Object<string, string>}
          */
@@ -295,8 +295,8 @@ export class ViewManager {
         this._changedSections = [];
 
         // Initialize views if not already done
-        if (!this.templates) {
-            this.templates = ViewTemplates;
+        if (!this.templates || Object.keys(this.templates).length === 0) {
+            this.templates = viewLoader.registry || {};
         }
 
         // Initialize current scope