plusui-native-core 0.1.50 → 0.1.53

package/Core/Features/Bindings/UNIFIED_SYSTEM.md

@@ -1,351 +0,0 @@
-# PlusUI Unified Binding System
-
-## One Macro to Rule Them All: `PLUSUI_BIND`
-
-The PlusUI framework now uses a **single, unified macro** for all frontend ↔ backend communication.
-
-### Simple. Type-Safe. Bidirectional.
-
-```cpp
-PLUSUI_BIND(name, returnType, ...paramTypes)
-```
-
-## How It Works
-
-### 1. Define Bindings in C++
-
-```cpp
-// src/features/myapp.hpp
-#pragma once
-#include <plusui/bindings.hpp>
-
-//====================================
-// Frontend → Backend (Methods)
-//====================================
-PLUSUI_BIND(getUserName, string, void)
-PLUSUI_BIND(setTheme, void, string)
-PLUSUI_BIND(calculate, int, int, int)
-PLUSUI_BIND(queryDatabase, json, string)
-
-//====================================
-// Backend → Frontend (Events)
-// Names starting with "on" = events
-//====================================
-PLUSUI_BIND(onDataUpdated, void, json)
-PLUSUI_BIND(onProgressUpdate, void, int)
-PLUSUI_BIND(onError, void, string)
-```
-
-### 2. Run Code Generation
-
-```bash
-# Generate type-safe TypeScript bindings
-plusui generate
-
-# Or directly:
-npx plusui-bindgen . ./src/Bindings
-```
-
-### 3. Use in TypeScript
-
-```typescript
-// Auto-generated: ./src/Bindings/bindings.gen.ts
-import { plusui } from './bindings.gen';
-
-//====================================
-// Call Backend Methods
-//====================================
-const name = await plusui.myapp.getUserName();
-await plusui.myapp.setTheme('dark');
-const result = await plusui.myapp.calculate(10, 20);
-const data = await plusui.myapp.queryDatabase('SELECT * FROM users');
-
-//====================================
-// Listen to Backend Events
-//====================================
-plusui.myapp.onDataUpdated((data) => {
-  console.log('Data changed:', data);
-  updateUI(data);
-});
-
-const unsubscribe = plusui.myapp.onProgressUpdate((percent) => {
-  setProgress(percent);
-});
-
-plusui.myapp.onError((error) => {
-  toast.error(error);
-});
-
-// Clean up when component unmounts
-unsubscribe();
-```
-
-### 4. Implement in C++
-
-```cpp
-// src/features/myapp.cpp
-#include "myapp.hpp"
-#include <plusui/bindings.hpp>
-
-using json = nlohmann::json;
-
-//====================================
-// Implement Methods
-//====================================
-std::string getUserName() {
-    return "PlusUI Developer";
-}
-
-void setTheme(const std::string& theme) {
-    applyTheme(theme);
-}
-
-int calculate(int x, int y) {
-    return x + y;
-}
-
-json queryDatabase(const std::string& sql) {
-    return db.execute(sql);
-}
-
-//====================================
-// Emit Events from C++
-//====================================
-void onDataChanged() {
-    json update = {
-        {"timestamp", getCurrentTime()},
-        {"records", getRecordCount()}
-    };
-    plusui::bindings::emitToFrontend("onDataUpdated", update);
-}
-
-void processFile(const std::string& path) {
-    for (int i = 0; i < 100; i++) {
-        // Do work...
-        
-        // Emit progress
-        plusui::bindings::emitToFrontend("onProgressUpdate", i);
-    }
-}
-```
-
-## Two Categories of Bindings
-
-### NativeBindings (Core Framework)
-
-Auto-detected based on your TypeScript imports:
-
-```typescript
-import { window, app, display } from 'plusui-native-core';
-
-// These automatically generate native bindings:
-await window.minimize();
-await app.quit();
-const displays = await display.getAll();
-```
-
-**Features:**
-- Window (minimize, maximize, show, hide, etc.)
-- App (quit, ready lifecycle)
-- Display (get displays)
-- Clipboard (read/write)
-- Keyboard (shortcuts)
-- Menu (native menus)
-- Tray (system tray)
-- Browser (open URLs)
-
-### CustomBindings (Your App Logic)
-
-Defined by **you** using `PLUSUI_BIND`:
-
-```cpp
-// Your custom features
-PLUSUI_BIND(authenticateUser, bool, string, string)
-PLUSUI_BIND(loadFile, string, string)
-PLUSUI_BIND(saveFile, void, string, string)
-PLUSUI_BIND(onFileChanged, void, json)
-```
-
-## Generated File Structure
-
-After running `plusui generate`:
-
-```
-src/Bindings/
-├── bindings.gen.ts              # Main unified TypeScript export
-├── bindings.gen.hpp             # C++ binding metadata
-├── bindings.report.json         # Generation report
-│
-├── NativeBindings/
-│   ├── CPP_IO/
-│   │   ├── core.bindings.gen.hpp
-│   │   └── core.bindings.gen.cpp
-│   └── WEB_IO/
-│       └── core.bindings.gen.ts
-│
-└── CustomBindings/
-    ├── CPP_IO/
-    │   ├── custom.bindings.gen.hpp
-    │   └── custom.bindings.gen.cpp
-    └── WEB_IO/
-        └── custom.bindings.gen.ts
-
-include/Bindings/               # Mirrored C++ headers for imports
-├── bindings.gen.hpp
-├── NativeBindings/
-│   └── CPP_IO/
-│       └── core.bindings.gen.hpp
-└── CustomBindings/
-    └── CPP_IO/
-        └── custom.bindings.gen.hpp
-```
-
-## Type Mapping
-
-| C++ Type              | TypeScript Type | Example         |
-|-----------------------|-----------------|-----------------|
-| `void`                | `void`          | No return       |
-| `bool`                | `boolean`       | `true`, `false` |
-| `int`, `float`, `double` | `number`       | `42`, `3.14`    |
-| `string`, `std::string` | `string`        | `"hello"`       |
-| `json`, `nlohmann::json` | `any`          | Objects, arrays |
-
-## Naming Conventions
-
-### Methods (Frontend → Backend)
-- Any descriptive name
-- Examples: `getUserData`, `calculate`, `saveFile`, `queryDatabase`
-
-### Events (Backend → Frontend)
-- **Must start with "on" prefix**
-- Examples: `onDataChanged`, `onError`, `onProgress`, `onFileUpdated`
-
-This makes the direction clear at a glance!
-
-## Import Styles
-
-### Recommended: Unified Import
-
-```typescript
-import { plusui } from './bindings.gen';
-
-// Access everything through plusui
-await plusui.myFeature.myMethod();
-plusui.myFeature.onEvent((data) => { });
-```
-
-### Alternative: Individual Imports
-
-```typescript
-import { myFeature, otherFeature } from './bindings.gen';
-
-// Direct access
-await myFeature.myMethod();
-myFeature.onEvent((data) => { });
-```
-
-## Best Practices
-
-✅ **Use PLUSUI_BIND for Everything**
-- Don't mix with manual bindings
-- One system = simple codebase
-
-✅ **Event Names Start with "on"**
-- Makes direction obvious
-- `onProgress`, `onError`, `onUpdate`
-
-✅ **Group Related Bindings**
-- `database.hpp` for DB bindings
-- `auth.hpp` for auth bindings
-- etc.
-
-✅ **Run Generate After Changes**
-```bash
-plusui generate
-```
-
-✅ **Use `json` for Complex Data**
-```cpp
-PLUSUI_BIND(getUser, json, int)  // Not: (string, string, int, bool, ...)
-```
-
-✅ **Clean Up Event Listeners**
-```typescript
-const unsubscribe = plusui.feature.onEvent(() => {});
-// Later:
-unsubscribe();
-```
-
-## Migration from Old System
-
-### Before (Multiple Macros)
-```cpp
-PLUSUI_METHOD(getUserName, string, void)
-PLUSUI_EVENT(onDataChanged, json)
-PLUSUI_SERVICE(dataService, json, string)
-PLUSUI_STREAM(logStream, string)
-```
-
-### After (Unified)
-```cpp
-PLUSUI_BIND(getUserName, string, void)
-PLUSUI_BIND(onDataChanged, void, json)
-PLUSUI_BIND(dataService, json, string)
-PLUSUI_BIND(logStream, void, string)  // Events use void + "on" prefix
-```
-
-## Runtime/Dynamic Bindings (Advanced)
-
-For advanced scenarios (plugins, hot-reload):
-
-```typescript
-import { registerMethod, registerEvent } from './bindings/custom_bindings';
-
-// Register at runtime
-registerMethod('dynamicMethod', async (params) => {
-  return processParams(params);
-});
-
-registerEvent('dynamicEvent', (data) => {
-  console.log('Dynamic event:', data);
-});
-```
-
-## Under the Hood
-
-### Compile Time
-1. `plusui-bindgen` scans all C++ files for `PLUSUI_BIND`
-2. Parses type signatures
-3. Auto-detects direction (method vs event)
-4. Generates TypeScript classes with proper types
-5. Generates C++ registration metadata
-
-### Runtime
-1. Frontend calls `plusui.feature.method(args)`
-2. TypeScript bridge serializes as JSON
-3. WebView IPC sends to C++ via `__invoke__`
-4. C++ dispatcher routes to registered handler
-5. Result serialized back to frontend
-6. Promise resolves with typed result
-
-### Events
-1. C++ calls `plusui::bindings::emitToFrontend(name, data)`
-2. Serializes JSON data
-3. WebView dispatches as CustomEvent
-4. Frontend listeners receive typed data
-
-## Summary
-
-**Old Way:**
-- Multiple macros (PLUSUI_METHOD, PLUSUI_EVENT, PLUSUI_SERVICE, PLUSUI_STREAM)
-- Confusing overlap between Events and Bindings
-- Manual type mapping
-
-**New Way:**
-- **One macro**: `PLUSUI_BIND`
-- **Simple naming**: methods vs events (starting with "on")
-- **Auto-generated**: Run `plusui generate`
-- **Type-safe**: Full TypeScript autocomplete
-- **Bidirectional**: Methods and events in one system
-
-**Result:** Clean, simple, powerful! 🚀

package/Core/Features/Event/Events.ts

@@ -1,166 +0,0 @@
-/**
- * PlusUI Event System - scalable bidirectional events
- * 
- * Backend:
- *   event::on("myEvent", callback)    // Listen for events from frontend
- *   event::once("myEvent", callback)  // Listen once
- *   event::emit("myEvent", data)      // Send events to frontend
- * 
- * Frontend:
- *   const stop = event.on("myEvent", callback) // Listen + unsubscribe
- *   event.once("myEvent", callback)            // Listen once
- *   event.emit("myEvent", data)                // Send events to backend
- * 
- * Users create custom event names anywhere.
- */
-
-type EventCallback<T = unknown> = (data: T) => void;
-type AnyEventCallback = (eventName: string, data: unknown) => void;
-export type Unsubscribe = () => void;
-
-const listeners = new Map<string, Set<EventCallback>>();
-const anyListeners = new Set<AnyEventCallback>();
-const attachedDomBridges = new Set<string>();
-
-let _invoke: ((method: string, args?: unknown[]) => Promise<unknown>) | null = null;
-
-export function setInvokeFn(fn: (method: string, args?: unknown[]) => Promise<unknown>) {
-  _invoke = fn;
-}
-
-async function invoke(method: string, args?: unknown[]): Promise<unknown> {
-  if (!_invoke) {
-    if (typeof window !== 'undefined' && (window as any).__invoke__) {
-      _invoke = (window as any).__invoke__;
-    } else {
-      throw new Error('Event API not initialized');
-    }
-  }
-  return _invoke!(method, args);
-}
-
-function validateEventName(name: string): void {
-  if (!name || !name.trim()) {
-    throw new Error('Event name must be a non-empty string');
-  }
-}
-
-function emitToLocalListeners(name: string, data: unknown): void {
-  const eventListeners = listeners.get(name);
-  if (eventListeners && eventListeners.size > 0) {
-    for (const callback of Array.from(eventListeners)) {
-      callback(data);
-    }
-  }
-
-  for (const callback of Array.from(anyListeners)) {
-    callback(name, data);
-  }
-}
-
-function ensureDomBridge(name: string): void {
-  if (typeof window === 'undefined' || attachedDomBridges.has(name)) {
-    return;
-  }
-
-  const domEvent = `plusui:event:${name}`;
-  const handler = (event: Event) => {
-    emitToLocalListeners(name, (event as CustomEvent).detail);
-  };
-
-  window.addEventListener(domEvent, handler as EventListener);
-  attachedDomBridges.add(name);
-}
-
-export const event = {
-  /**
-   * Listen for events from backend
-   * Returns an unsubscribe function.
-   */
-  on: <T = unknown>(name: string, callback: EventCallback<T>): Unsubscribe => {
-    validateEventName(name);
-
-    if (!listeners.has(name)) {
-      listeners.set(name, new Set());
-    }
-    listeners.get(name)!.add(callback as EventCallback);
-
-    ensureDomBridge(name);
-
-    return () => {
-      event.off(name, callback as EventCallback);
-    };
-  },
-
-  /**
-   * Listen once for an event from backend.
-   */
-  once: <T = unknown>(name: string, callback: EventCallback<T>): Unsubscribe => {
-    validateEventName(name);
-
-    let unsubscribe: Unsubscribe = () => {};
-    const wrapped = (data: unknown) => {
-      unsubscribe();
-      callback(data as T);
-    };
-
-    unsubscribe = event.on(name, wrapped);
-    return unsubscribe;
-  },
-
-  /**
-   * Listen to every incoming backend event that has a registered bridge.
-   */
-  onAny: (callback: AnyEventCallback): Unsubscribe => {
-    if (typeof callback !== 'function') {
-      throw new Error('onAny callback must be a function');
-    }
-
-    anyListeners.add(callback);
-
-    return () => {
-      anyListeners.delete(callback);
-    };
-  },
-
-  /**
-   * Remove one callback from a named event.
-   */
-  off: (name: string, callback: EventCallback): boolean => {
-    validateEventName(name);
-
-    const set = listeners.get(name);
-    if (!set) {
-      return false;
-    }
-
-    const removed = set.delete(callback);
-    if (set.size === 0) {
-      listeners.delete(name);
-    }
-
-    return removed;
-  },
-
-  /**
-   * Remove all listeners. If name is set, clear only that event.
-   */
-  clear: (name?: string): void => {
-    if (name === undefined) {
-      listeners.clear();
-      anyListeners.clear();
-      return;
-    }
-
-    validateEventName(name);
-    listeners.delete(name);
-  },
-
-  /**
-   * Emit events to backend.
-   */
-  emit: async (name: string, data: unknown): Promise<void> => {
-    validateEventName(name);
-    await invoke('event.emit', [name, data]);
-  },
-};

package/Core/Features/Event/events.cpp

@@ -1,200 +0,0 @@
-// Event API implementation
-#include <plusui/events.hpp>
-#include <functional>
-#include <unordered_map>
-#include <vector>
-#include <mutex>
-#include <atomic>
-#include <algorithm>
-#include <utility>
-#include <iostream>
-
-namespace plusui {
-namespace event {
-
-struct ListenerEntry {
-    ListenerId id;
-    EventCallback callback;
-    bool once;
-};
-
-struct AnyListenerEntry {
-    ListenerId id;
-    AnyEventCallback callback;
-    bool once;
-};
-
-// Event listeners registry
-static std::unordered_map<std::string, std::vector<ListenerEntry>> listeners;
-static std::vector<AnyListenerEntry> any_listeners;
-static std::mutex mutex;
-static std::atomic<ListenerId> next_listener_id{1};
-
-// Bridge to frontend (set by webview initialization)
-std::function<void(const std::string&, const EventData&)> __bridge_to_frontend__;
-
-// Listen for events from frontend
-ListenerId on(const std::string& name, EventCallback callback) {
-    if (name.empty() || !callback) {
-        return 0;
-    }
-
-    const ListenerId id = next_listener_id.fetch_add(1);
-    std::lock_guard<std::mutex> lock(mutex);
-    listeners[name].push_back({id, std::move(callback), false});
-    return id;
-}
-
-ListenerId once(const std::string& name, EventCallback callback) {
-    if (name.empty() || !callback) {
-        return 0;
-    }
-
-    const ListenerId id = next_listener_id.fetch_add(1);
-    std::lock_guard<std::mutex> lock(mutex);
-    listeners[name].push_back({id, std::move(callback), true});
-    return id;
-}
-
-ListenerId on_any(AnyEventCallback callback) {
-    if (!callback) {
-        return 0;
-    }
-
-    const ListenerId id = next_listener_id.fetch_add(1);
-    std::lock_guard<std::mutex> lock(mutex);
-    any_listeners.push_back({id, std::move(callback), false});
-    return id;
-}
-
-bool off(const std::string& name, ListenerId id) {
-    if (name.empty() || id == 0) {
-        return false;
-    }
-
-    std::lock_guard<std::mutex> lock(mutex);
-    auto it = listeners.find(name);
-    if (it == listeners.end()) {
-        return false;
-    }
-
-    auto& bucket = it->second;
-    const auto old_size = bucket.size();
-    bucket.erase(
-        std::remove_if(bucket.begin(), bucket.end(), [id](const ListenerEntry& entry) {
-            return entry.id == id;
-        }),
-        bucket.end()
-    );
-    const auto new_size = bucket.size();
-
-    if (bucket.empty()) {
-        listeners.erase(it);
-    }
-
-    return new_size != old_size;
-}
-
-bool off_any(ListenerId id) {
-    if (id == 0) {
-        return false;
-    }
-
-    std::lock_guard<std::mutex> lock(mutex);
-    const auto old_size = any_listeners.size();
-    any_listeners.erase(
-        std::remove_if(any_listeners.begin(), any_listeners.end(), [id](const AnyListenerEntry& entry) {
-            return entry.id == id;
-        }),
-        any_listeners.end()
-    );
-
-    return any_listeners.size() != old_size;
-}
-
-std::size_t off_all(const std::string& name) {
-    if (name.empty()) {
-        return 0;
-    }
-
-    std::lock_guard<std::mutex> lock(mutex);
-    auto it = listeners.find(name);
-    if (it == listeners.end()) {
-        return 0;
-    }
-
-    const auto removed = it->second.size();
-    listeners.erase(it);
-    return removed;
-}
-
-void clear() {
-    std::lock_guard<std::mutex> lock(mutex);
-    listeners.clear();
-    any_listeners.clear();
-}
-
-// Emit events to frontend
-void emit(const std::string& name, const EventData& data) {
-    if (__bridge_to_frontend__) {
-        __bridge_to_frontend__(name, data);
-    }
-}
-
-// Internal: Receive event from frontend (called by binding system)
-// This is registered as "event.emit" in the IPC handlers
-void __dispatch_from_frontend__(const std::string& name, const EventData& data) {
-    std::vector<ListenerEntry> named_callbacks;
-    std::vector<AnyListenerEntry> global_callbacks;
-
-    {
-        std::lock_guard<std::mutex> lock(mutex);
-        auto it = listeners.find(name);
-        if (it != listeners.end()) {
-            named_callbacks = it->second;
-            it->second.erase(
-                std::remove_if(it->second.begin(), it->second.end(), [](const ListenerEntry& entry) {
-                    return entry.once;
-                }),
-                it->second.end()
-            );
-
-            if (it->second.empty()) {
-                listeners.erase(it);
-            }
-        }
-
-        global_callbacks = any_listeners;
-        any_listeners.erase(
-            std::remove_if(any_listeners.begin(), any_listeners.end(), [](const AnyListenerEntry& entry) {
-                return entry.once;
-            }),
-            any_listeners.end()
-        );
-    }
-
-    for (const auto& entry : named_callbacks) {
-        try {
-            entry.callback(data);
-        } catch (const std::exception& ex) {
-            std::cerr << "[PlusUI:event] listener error for '" << name << "': " << ex.what() << std::endl;
-        } catch (...) {
-            std::cerr << "[PlusUI:event] listener error for '" << name << "': unknown exception" << std::endl;
-        }
-    }
-
-    for (const auto& entry : global_callbacks) {
-        try {
-            entry.callback(name, data);
-        } catch (const std::exception& ex) {
-            std::cerr << "[PlusUI:event] on_any listener error for '" << name << "': " << ex.what() << std::endl;
-        } catch (...) {
-            std::cerr << "[PlusUI:event] on_any listener error for '" << name << "': unknown exception" << std::endl;
-        }
-    }
-}
-
-} // namespace event
-} // namespace plusui
-
-