plusui-native-core 0.1.8 → 0.1.10

package/Core/CMakeLists.txt

@@ -19,7 +19,8 @@ else()
     add_definitions(-DPLUSUI_GTK)
 endif()
 
-add_library(plusui STATIC
+    Features/Bindings/NativeBindings/native_bindings.cpp
+    Features/Bindings/CustomBindings/custom_bindings.cpp
     Features/App/app.cpp
     Features/Window/window.cpp
     Features/WindowManager/window_manager.cpp

package/Core/Features/Bindings/ARCHITECTURE.md

@@ -0,0 +1,328 @@
+# PlusUI Binding System Architecture
+
+## Complete Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         DEVELOPER WORKFLOW                          │
+└─────────────────────────────────────────────────────────────────────┘
+
+1. Define Bindings in C++
+   ┌──────────────────────────────────────────────────┐
+   │ // src/features/myapp.hpp                       │
+   │ #include <plusui/bindings.hpp>                  │
+   │                                                  │
+   │ // Methods (Frontend → Backend)                 │
+   │ PLUSUI_BIND(getUserName, string, void)          │
+   │ PLUSUI_BIND(calculate, int, int, int)           │
+   │                                                  │
+   │ // Events (Backend → Frontend, start with "on") │
+   │ PLUSUI_BIND(onDataUpdated, void, json)          │
+   └──────────────────────────────────────────────────┘
+                            ↓
+
+2. Run Code Generation
+   ┌──────────────────────────────────────────────────┐
+   │ $ plusui generate                                │
+   │                                                  │
+   │ plusui-bindgen:                                  │
+   │ - Scans all C++ files                           │
+   │ - Finds PLUSUI_BIND macros                      │
+   │ - Detects native core usage                     │
+   │ - Generates TypeScript bindings                 │
+   │ - Generates C++ metadata                        │
+   └──────────────────────────────────────────────────┘
+                            ↓
+
+3. Generated Files
+   ┌──────────────────────────────────────────────────┐
+   │ src/Bindings/                                    │
+   │ ├── bindings.gen.ts      ← Import this!         │
+   │ ├── bindings.gen.hpp     ← C++ metadata         │
+   │ ├── NativeBindings/      ← Core features        │
+   │ │   ├── CPP_IO/                                  │
+   │ │   └── WEB_IO/                                  │
+   │ └── CustomBindings/      ← Your features        │
+   │     ├── CPP_IO/                                  │
+   │     └── WEB_IO/                                  │
+   └──────────────────────────────────────────────────┘
+                            ↓
+
+4. Use in TypeScript
+   ┌──────────────────────────────────────────────────┐
+   │ import { plusui } from './bindings.gen';        │
+   │                                                  │
+   │ // Call backend                                  │
+   │ const name = await plusui.myapp.getUserName();  │
+   │ const result = await plusui.myapp.calculate(5,3);│
+   │                                                  │
+   │ // Listen to events                              │
+   │ plusui.myapp.onDataUpdated((data) => {          │
+   │   updateUI(data);                                │
+   │ });                                              │
+   └──────────────────────────────────────────────────┘
+                            ↓
+
+5. Build & Run
+   ┌──────────────────────────────────────────────────┐
+   │ $ plusui build                                   │
+   │                                                  │
+   │ - Compiles C++ with CMake                       │
+   │ - Bundles frontend with Vite                    │
+   │ - Links bindings at runtime                     │
+   │ - Creates single executable                     │
+   └──────────────────────────────────────────────────┘
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                         RUNTIME FLOW                                │
+└─────────────────────────────────────────────────────────────────────┘
+
+Frontend → Backend (Method Call)
+──────────────────────────────────
+
+TypeScript:
+  plusui.myapp.getUserName()
+         ↓
+  Generated binding class calls:
+    invoke("myapp.getUserName", [])
+         ↓
+  WebView bridge serializes:
+    { id: 1, method: "myapp.getUserName", params: [] }
+         ↓
+  IPC via window.__invoke__
+         ↓
+C++:
+  Binding dispatcher receives JSON
+         ↓
+  Routes to registered handler
+         ↓
+  Executes: getUserName()
+         ↓
+  Returns: "John Doe"
+         ↓
+  Serializes result to JSON
+         ↓
+  WebView bridge sends back:
+    { id: 1, result: "John Doe" }
+         ↓
+TypeScript:
+  Promise resolves with "John Doe"
+         ↓
+  const name = "John Doe"  ✓
+
+
+Backend → Frontend (Event Emission)
+────────────────────────────────────
+
+C++:
+  plusui::bindings::emitToFrontend("onDataUpdated", {
+    {"count", 42},
+    {"status", "active"}
+  })
+         ↓
+  Serializes JSON data
+         ↓
+  WebView dispatches CustomEvent:
+    new CustomEvent("plusui:binding:myapp.onDataUpdated", {
+      detail: { count: 42, status: "active" }
+    })
+         ↓
+TypeScript:
+  window.addEventListener receives event
+         ↓
+  Generated binding routes to handlers:
+    plusui.myapp.onDataUpdated((data) => { ... })
+         ↓
+  Handler executes with typed data:
+    data.count === 42
+    data.status === "active"  ✓
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                         TYPE SYSTEM                                 │
+└─────────────────────────────────────────────────────────────────────┘
+
+PLUSUI_BIND(methodName, returnType, ...paramTypes)
+                  │           │            │
+                  │           │            └─→ Parameter types (0-N)
+                  │           └──────────────→ Return type
+                  └──────────────────────────→ Method/Event name
+
+Auto-Detection Rules:
+  • Name starts with "on" + returnType is void = EVENT
+  • Otherwise = METHOD
+
+Type Mapping Table:
+  ┌──────────────────┬─────────────────┬─────────────────┐
+  │  C++ Type        │  TS Type        │  Example        │
+  ├──────────────────┼─────────────────┼─────────────────┤
+  │  void            │  void           │  (no return)    │
+  │  bool            │  boolean        │  true, false    │
+  │  int, float      │  number         │  42, 3.14       │
+  │  string          │  string         │  "hello"        │
+  │  json            │  any            │  {}, []         │
+  └──────────────────┴─────────────────┴─────────────────┘
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                    BINDING CATEGORIES                               │
+└─────────────────────────────────────────────────────────────────────┘
+
+NativeBindings (Core Framework)
+────────────────────────────────
+Auto-detected from imports:
+  import { window, app, display } from 'plusui-native-core';
+
+Features:
+  • Window - minimize, maximize, show, hide, setTitle, etc.
+  • App - quit, ready, getVersion, etc.
+  • Display - getAll, getPrimary, etc.
+  • Clipboard - readText, writeText, etc.
+  • Keyboard - registerShortcut, etc.
+  • Menu - create, show, etc.
+  • Tray - create, setIcon, setTooltip, etc.
+  • Browser - open, etc.
+
+Location: node_modules/plusui-native-core/Core/Features/
+
+
+CustomBindings (Your App Logic)
+────────────────────────────────
+Defined by you with PLUSUI_BIND:
+
+Examples:
+  • Database operations
+  • Authentication/authorization
+  • File system operations
+  • Network requests
+  • Plugin systems
+  • Custom business logic
+
+Location: Your project src/ files
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                    GENERATED FILE STRUCTURE                         │
+└─────────────────────────────────────────────────────────────────────┘
+
+src/Bindings/
+├── bindings.gen.ts              # ← MAIN IMPORT
+│   export const plusui = {
+│     window: WindowBindings,
+│     app: AppBindings,
+│     myFeature: MyFeatureBindings,
+│     ...
+│   }
+│
+├── bindings.gen.hpp             # C++ metadata
+├── bindings.report.json         # Generation report
+│
+├── NativeBindings/
+│   ├── CPP_IO/
+│   │   ├── core.bindings.gen.hpp    # Core registration
+│   │   └── core.bindings.gen.cpp    # Implementation stub
+│   └── WEB_IO/
+│       └── core.bindings.gen.ts     # Core TS classes
+│
+└── CustomBindings/
+    ├── CPP_IO/
+    │   ├── custom.bindings.gen.hpp  # Custom registration
+    │   └── custom.bindings.gen.cpp  # Implementation stub
+    └── WEB_IO/
+        └── custom.bindings.gen.ts   # Custom TS classes
+
+include/Bindings/                # Mirrored C++ headers
+├── bindings.gen.hpp
+├── NativeBindings/...
+└── CustomBindings/...
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                         BEST PRACTICES                              │
+└─────────────────────────────────────────────────────────────────────┘
+
+1. ✅ Use PLUSUI_BIND for everything
+   ❌ Don't mix with manual bindings
+
+2. ✅ Events start with "on" prefix
+   ✓ onDataChanged, onError, onProgress
+   ✗ dataChanged, error, progress
+
+3. ✅ Group related bindings in files
+   src/features/
+   ├── database.hpp    (DB bindings)
+   ├── auth.hpp        (Auth bindings)
+   └── files.hpp       (File bindings)
+
+4. ✅ Use json for complex data
+   PLUSUI_BIND(getUser, json, int)
+   ❌ Not: (string, string, int, bool, ...)
+
+5. ✅ Run generate after changes
+   $ plusui generate
+
+6. ✅ Clean up event listeners
+   const unsub = plusui.feature.onEvent(...);
+   return () => unsub();
+
+7. ✅ Handle errors gracefully
+   try {
+     await plusui.feature.method();
+   } catch (error) {
+     // Handle error
+   }
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                         COMPARISON                                  │
+└─────────────────────────────────────────────────────────────────────┘
+
+Old System (❌ Deprecated)
+──────────────────────────
+• Multiple macros: PLUSUI_METHOD, PLUSUI_EVENT, PLUSUI_SERVICE
+• Confusing overlap between Events and Bindings docs
+• Manual type mapping
+• Inconsistent naming
+
+New System (✅ Recommended)
+───────────────────────────
+• Single macro: PLUSUI_BIND
+• Clear distinction: methods vs events (naming convention)
+• Auto-generated types
+• Simple, unified system
+• One import: import { plusui } from './bindings.gen'
+
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                         QUICK REFERENCE                             │
+└─────────────────────────────────────────────────────────────────────┘
+
+Define Binding:
+  PLUSUI_BIND(name, returnType, ...paramTypes)
+
+Methods (Frontend → Backend):
+  PLUSUI_BIND(getUserData, json, int)
+
+Events (Backend → Frontend):
+  PLUSUI_BIND(onUserLoggedIn, void, json)
+
+Generate:
+  $ plusui generate
+
+Use in TypeScript:
+  import { plusui } from './bindings.gen';
+  
+  // Methods
+  await plusui.feature.method(args);
+  
+  // Events
+  const unsub = plusui.feature.onEvent((data) => { });
+
+Emit from C++:
+  plusui::bindings::emitToFrontend("onEvent", jsonData);
+
+
+═══════════════════════════════════════════════════════════════════════
+Simple. Type-Safe. Bidirectional. 🚀
+═══════════════════════════════════════════════════════════════════════

package/Core/Features/Bindings/CustomBindings/custom_bindings.cpp

@@ -0,0 +1,53 @@
+#include <plusui/bindings.hpp>
+#include <map>
+#include <string>
+
+namespace plusui {
+namespace bindings {
+
+// Runtime method registry (advanced use)
+static std::map<std::string, InvokeHandler> runtime_methods;
+
+// Runtime event registry (advanced use)
+static std::map<std::string, EventHandler> runtime_events;
+
+void registerMethod(const std::string& name, InvokeHandler handler) {
+    runtime_methods[name] = handler;
+}
+
+void registerEvent(const std::string& name, EventHandler handler) {
+    runtime_events[name] = handler;
+}
+
+void emitToFrontend(const std::string& name, const json& data) {
+    // Emit event to frontend via webview
+    // Implementation depends on webview instance
+    // This will be wired up by the generated binding code
+}
+
+json invokeFromFrontend(const std::string& name, const json& params) {
+    auto it = runtime_methods.find(name);
+    if (it != runtime_methods.end()) {
+        return it->second(params);
+    }
+    return json{"error", "Method not found: " + name};
+}
+
+std::vector<std::string> getRegisteredMethods() {
+    std::vector<std::string> result;
+    for (const auto& pair : runtime_methods) {
+        result.push_back(pair.first);
+    }
+    return result;
+}
+
+std::vector<std::string> getRegisteredEvents() {
+    std::vector<std::string> result;
+    for (const auto& pair : runtime_events) {
+        result.push_back(pair.first);
+    }
+    return result;
+}
+
+} // namespace bindings
+} // namespace plusui

package/Core/Features/Bindings/CustomBindings/custom_bindings.ts

@@ -0,0 +1,35 @@
+/**
+ * CustomBindings - Runtime Registration
+ * 
+ * This file provides runtime binding registration for advanced use cases.
+ * Most users should use PLUSUI_BIND macro for compile-time bindings.
+ * 
+ * Use this for:
+ * - Dynamic runtime method registration
+ * - Plugin systems
+ * - Hot-reloading scenarios
+ */
+
+export type BindingHandler = (params: unknown[]) => Promise<unknown> | unknown;
+export type EventHandler = (data: unknown) => void;
+
+/**
+ * Register a method at runtime (advanced)
+ */
+export function registerMethod(name: string, handler: BindingHandler): void {
+  const w = typeof window !== 'undefined' ? window as any : globalThis as any;
+  if (!w.__plusui_runtime_methods__) {
+    w.__plusui_runtime_methods__ = new Map<string, BindingHandler>();
+  }
+  w.__plusui_runtime_methods__.set(name, handler);
+}
+
+/**
+ * Register an event listener at runtime (advanced)
+ */
+export function registerEvent(name: string, handler: EventHandler): () => void {
+  const eventName = `plusui:binding:${name}`;
+  const listener = (e: Event) => handler((e as CustomEvent).detail);
+  window.addEventListener(eventName, listener);
+  return () => window.removeEventListener(eventName, listener);
+}

package/Core/Features/Bindings/EXAMPLE_USAGE.hpp

@@ -0,0 +1,143 @@
+/**
+ * Example: Using the Unified PLUSUI_BIND System
+ * 
+ * This example demonstrates how to create custom bindings
+ * for a simple task management app.
+ */
+
+#pragma once
+#include <plusui/bindings.hpp>
+#include <string>
+#include <vector>
+
+namespace taskapp {
+
+using json = nlohmann::json;
+
+//========================================
+// Frontend → Backend Methods
+//========================================
+
+// Get all tasks
+PLUSUI_BIND(getAllTasks, json, void)
+
+// Add a new task
+PLUSUI_BIND(addTask, int, string, string)
+
+// Complete a task
+PLUSUI_BIND(completeTask, bool, int)
+
+// Delete a task
+PLUSUI_BIND(deleteTask, bool, int)
+
+// Get task by ID
+PLUSUI_BIND(getTask, json, int)
+
+//========================================
+// Backend → Frontend Events
+// (Names starting with "on")
+//========================================
+
+// Fired when a task is added
+PLUSUI_BIND(onTaskAdded, void, json)
+
+// Fired when a task is completed
+PLUSUI_BIND(onTaskCompleted, void, int)
+
+// Fired when a task is deleted
+PLUSUI_BIND(onTaskDeleted, void, int)
+
+// Fired when tasks are reordered
+PLUSUI_BIND(onTasksReordered, void, json)
+
+//========================================
+// Implementation (would be in .cpp file)
+//========================================
+
+struct Task {
+    int id;
+    std::string title;
+    std::string description;
+    bool completed;
+};
+
+static std::vector<Task> tasks;
+static int nextId = 1;
+
+// Methods
+json getAllTasks() {
+    json result = json::array();
+    for (const auto& task : tasks) {
+        result.push_back({
+            {"id", task.id},
+            {"title", task.title},
+            {"description", task.description},
+            {"completed", task.completed}
+        });
+    }
+    return result;
+}
+
+int addTask(const std::string& title, const std::string& description) {
+    Task task = {
+        .id = nextId++,
+        .title = title,
+        .description = description,
+        .completed = false
+    };
+    
+    tasks.push_back(task);
+    
+    // Emit event to frontend
+    plusui::bindings::emitToFrontend("onTaskAdded", {
+        {"id", task.id},
+        {"title", task.title},
+        {"description", task.description},
+        {"completed", task.completed}
+    });
+    
+    return task.id;
+}
+
+bool completeTask(int id) {
+    for (auto& task : tasks) {
+        if (task.id == id) {
+            task.completed = true;
+            
+            // Emit event
+            plusui::bindings::emitToFrontend("onTaskCompleted", id);
+            return true;
+        }
+    }
+    return false;
+}
+
+bool deleteTask(int id) {
+    auto it = std::find_if(tasks.begin(), tasks.end(), 
+                          [id](const Task& t) { return t.id == id; });
+    
+    if (it != tasks.end()) {
+        tasks.erase(it);
+        
+        // Emit event
+        plusui::bindings::emitToFrontend("onTaskDeleted", id);
+        return true;
+    }
+    return false;
+}
+
+json getTask(int id) {
+    for (const auto& task : tasks) {
+        if (task.id == id) {
+            return {
+                {"id", task.id},
+                {"title", task.title},
+                {"description", task.description},
+                {"completed", task.completed}
+            };
+        }
+    }
+    return nullptr;
+}
+
+} // namespace taskapp