jsgui3-server 0.0.147 → 0.0.148

package/admin-ui/client.js

@@ -0,0 +1,213 @@
+const jsgui = require('jsgui3-client');
+const { controls, Control, mixins } = jsgui;
+const Active_HTML_Document = require('../controls/Active_HTML_Document');
+
+class Admin_Page extends Active_HTML_Document {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'admin_page';
+        super(spec);
+        const { context } = this;
+
+        if (typeof this.body.add_class === 'function') {
+            this.body.add_class('admin-page');
+        }
+
+        const compose = () => {
+            // Sidebar
+            const sidebar = new controls.div({ context, class: 'admin-sidebar' });
+            this.body.add(sidebar);
+            this.sidebar = sidebar;
+
+            // Sidebar Header
+            const brand = new controls.div({ context, class: 'admin-brand' });
+            brand.add(new controls.span({ context, class: 'brand-icon' }).add('⚙️'));
+            brand.add(new controls.span({ context, class: 'brand-text' }).add('jsgui3 Admin'));
+            sidebar.add(brand);
+
+            // Menu Container (Placeholder for Resource_List and Observables_List)
+            const menu = new controls.div({ context, class: 'admin-menu' });
+            sidebar.add(menu);
+            this.menu = menu;
+
+            this._add_menu_item('Overview', 'overview', true);
+            this._add_menu_item('Resources', 'resources');
+            this._add_menu_item('Observables', 'observables');
+            this._add_menu_item('Settings', 'settings');
+
+
+            // Main Content Area
+            const main = new controls.div({ context, class: 'admin-main' });
+            this.body.add(main);
+            this.main = main;
+
+            // Top Bar
+            const top_bar = new controls.div({ context, class: 'admin-top-bar' });
+            main.add(top_bar);
+
+            // Breadcrumbs / Title
+            this.page_title = new controls.h2({ context, class: 'page-title' });
+            this.page_title.add('Overview');
+            top_bar.add(this.page_title);
+
+            // Content Panel
+            const content = new controls.div({ context, class: 'admin-content' });
+            main.add(content);
+            this.content = content;
+
+            // Default content (Overview)
+            this._render_overview();
+        };
+
+        if (!spec.el) {
+            compose();
+        }
+    }
+
+    _add_menu_item(label, id, active = false) {
+        const item = new controls.div({
+            context: this.context,
+            class: `menu-item ${active ? 'active' : ''}`
+        });
+        item.dom.attributes['data-id'] = id;
+        item.add(label);
+        this.menu.add(item);
+        return item;
+    }
+
+    _render_overview() {
+        // Clear main content area (this.content is the admin-content div)
+        if (this.content && this.content.content && typeof this.content.content.clear === 'function') {
+            this.content.content.clear();
+        }
+
+        const welcome = new controls.div({ context: this.context, class: 'welcome-card' });
+        welcome.add(new controls.h3({ context: this.context }).add('Welcome directly to jsgui3-server Admin'));
+        welcome.add(new controls.p({ context: this.context }).add('Select a resource from the sidebar to inspect.'));
+        this.content.add(welcome);
+    }
+
+    activate() {
+        if (!this.__active) {
+            super.activate();
+
+            // Handle menu clicks
+            const menu_items = document.querySelectorAll('.menu-item');
+            menu_items.forEach(el => {
+                el.addEventListener('click', () => {
+                    // Update Active State
+                    menu_items.forEach(i => i.classList.remove('active'));
+                    el.classList.add('active');
+
+                    // Update Title
+                    const id = el.getAttribute('data-id');
+                    const label = el.innerText;
+                    document.querySelector('.page-title').innerText = label;
+
+                    // Placeholder navigation logic
+                    console.log('Navigate to:', id);
+                });
+            });
+        }
+    }
+}
+
+Admin_Page.css = `
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { 
+    background: #1a1a2e; 
+    color: #e0e0e0; 
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    height: 100vh;
+    overflow: hidden;
+}
+.admin-page {
+    display: grid;
+    grid-template-columns: 260px 1fr;
+    height: 100%;
+}
+
+/* Sidebar */
+.admin-sidebar {
+    background: #16213e;
+    border-right: 1px solid #2a2a4a;
+    display: flex;
+    flex-direction: column;
+}
+.admin-brand {
+    padding: 20px;
+    font-size: 1.2rem;
+    font-weight: bold;
+    color: #fff;
+    border-bottom: 1px solid #2a2a4a;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+.brand-icon { filter: drop-shadow(0 0 5px rgba(255,255,255,0.3)); }
+
+.admin-menu {
+    flex: 1;
+    padding: 20px 0;
+    overflow-y: auto;
+}
+.menu-item {
+    padding: 12px 24px;
+    cursor: pointer;
+    border-left: 3px solid transparent;
+    transition: all 0.2s;
+    color: #a0a0b0;
+}
+.menu-item:hover {
+    background: rgba(255,255,255,0.05);
+    color: #fff;
+}
+.menu-item.active {
+    background: rgba(79, 172, 254, 0.1);
+    color: #4facfe;
+    border-left-color: #4facfe;
+}
+
+/* Main Area */
+.admin-main {
+    display: flex;
+    flex-direction: column;
+    background: #1a1a2e;
+}
+.admin-top-bar {
+    height: 64px;
+    border-bottom: 1px solid #2a2a4a;
+    display: flex;
+    align-items: center;
+    padding: 0 30px;
+    background: #16213e;
+}
+.page-title {
+    font-size: 1.2rem;
+    font-weight: 500;
+    color: #fff;
+}
+
+.admin-content {
+    flex: 1;
+    overflow-y: auto;
+    padding: 30px;
+    position: relative;
+}
+
+/* Cards */
+.welcome-card {
+    background: #2a2a4a;
+    padding: 40px;
+    border-radius: 12px;
+    text-align: center;
+    max-width: 600px;
+    margin: 40px auto;
+    border: 1px solid #3a3a5a;
+    box-shadow: 0 4px 20px rgba(0,0,0,0.2);
+}
+.welcome-card h3 { color: #fff; margin-bottom: 15px; }
+.welcome-card p { color: #a0a0b0; }
+`;
+
+controls.Admin_Page = Admin_Page;
+module.exports = jsgui;

package/admin-ui/server.js

@@ -0,0 +1,104 @@
+const jsgui = require('./client');
+const { Admin_Page } = jsgui.controls;
+const { each } = jsgui;
+
+class Admin_Module {
+    constructor(server) {
+        this.server = server;
+        this.setup_routes();
+    }
+
+    setup_routes() {
+        const { server } = this;
+
+        // 1. Main Admin Page Route
+        // Using a custom Website_Resource for the admin app
+        // We register Admin_Page as the content control
+
+        // Manual route setup to render the page
+        // (Similar to how examples work, but integrated)
+
+        // We'll expose a 'setup' method that the main server calls
+        // Or we can attach directly if we have access to the router
+    }
+
+    // Called by the main server to attach admin functionality
+    attach_to_router(router) {
+        console.log('[Admin_Module] Attaching /admin routes...');
+
+        // API: List Resources
+        // GET /api/admin/resources
+        router.set_route('/api/admin/resources', (req, res) => {
+            const resources_data = this.get_resources_tree();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(resources_data));
+        });
+
+        // API: List Observables
+        // GET /api/admin/observables
+        router.set_route('/api/admin/observables', (req, res) => {
+            const observables = this.get_observables_list();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(observables));
+        });
+    }
+
+    get_resources_tree() {
+        const pool = this.server.resource_pool;
+        const tree = {
+            name: 'Root',
+            type: 'pool',
+            children: []
+        };
+
+        if (pool && pool.resources) {
+            // Need to iterate pool resources safely
+            // resource_pool.resources is likely a Collection or array
+            const resources = pool.resources._arr || []; // Assuming Data_Structures.Collection
+
+            resources.forEach(res => {
+                tree.children.push({
+                    name: res.name || 'Unnamed Resource',
+                    type: res.constructor.name
+                });
+            });
+        }
+        return tree;
+    }
+
+    get_observables_list() {
+        // We need a way to track all published observables
+        // Ideally, HTTP_Observable_Publisher instances are stored in the resource pool or a specific list
+
+        // For now, we'll scan the router for observable publishers
+        // This relies on the server exposing its router/routes map
+        const observables = [];
+
+        // Implementation detail: server.router doesn't expose a simple list of routes easily in standard Router
+        // We might need to track them when publish_observable is called.
+        // But we can look at server.resource_pool for publishers
+
+        const pool = this.server.resource_pool;
+        if (pool && pool.resources) {
+            const resources = pool.resources._arr || [];
+            resources.forEach(res => {
+                // Check if it's an observable publisher
+                // Robust check: does it have 'obs' property and handle_http? 
+                // Or check constructor name if available
+                if (res.constructor.name === 'Observable_Publisher' || (res.obs && res.handle_http)) {
+                    observables.push({
+                        name: res.name || 'Observable',
+                        route: '?', // Route might not be stored on the resource itself, but on the router
+                        schema: res.schema,
+                        status: res.is_paused ? 'paused' : 'active',
+                        connections: res.active_sse_connections ? res.active_sse_connections.size : 0
+                    });
+                }
+            });
+        }
+
+        return observables;
+    }
+}
+
+module.exports = Admin_Module;

package/client/controls/auto-observable.js

@@ -0,0 +1,207 @@
+const jsgui = require('jsgui3-client');
+const { Control, controls } = jsgui;
+
+class Auto_Observable_UI extends Control {
+    constructor(spec = {}) {
+        spec.__type_name = spec.__type_name || 'auto_observable_ui';
+        super(spec);
+        this.add_class('auto-observable-ui');
+
+        this.url = spec.url;
+        this.obs = spec.obs;
+
+        // Container for the dynamic content
+        this.content_container = new controls.div({
+            context: this.context,
+            class: 'content-container'
+        });
+        this.add(this.content_container);
+
+        // Status indicator
+        this.status_indicator = new controls.div({
+            context: this.context,
+            class: 'status-indicator status-connecting'
+        });
+        this.add(this.status_indicator);
+    }
+
+    activate() {
+        if (!this.__active) {
+            super.activate();
+            this._connect();
+        }
+    }
+
+    _connect() {
+        let obs = this.obs;
+        if (!obs && this.url) {
+            obs = new jsgui.Remote_Observable({ url: this.url });
+            this.obs = obs;
+        }
+
+        if (!obs) return;
+
+        obs.on('connect', () => {
+            this.status_indicator.remove_class('status-connecting');
+            this.status_indicator.add_class('status-connected');
+            this.status_indicator.dom.innerText = 'Connected';
+        });
+
+        obs.on('schema', (schema) => {
+            console.log('Schema received:', schema);
+            this._build_ui_from_schema(schema);
+        });
+
+        obs.on('next', (data) => {
+            // If we haven't received a schema yet, maybe infer it or just display raw?
+            // For now, if we built the UI, we update it.
+            if (this._update_handler) {
+                this._update_handler(data);
+            } else if (!this._ui_built) {
+                // Infer simple schema if not provided?
+                // Or just show raw JSON
+                this._build_default_ui(data);
+                this._ui_built = true;
+                if (this._update_handler) this._update_handler(data);
+            }
+        });
+
+        obs.on('error', (err) => {
+            this.status_indicator.add_class('status-error');
+            this.status_indicator.dom.innerText = 'Error: ' + err.message;
+        });
+
+        obs.connect();
+    }
+
+    _build_ui_from_schema(schema) {
+        if (this._ui_built) return; // Don't rebuild for now
+        this._ui_built = true;
+
+        this.content_container.content.clear();
+
+        const type = schema.type || (schema.output_type ? schema.output_type : 'unknown');
+
+        if (type === 'int' || type === 'number') {
+            this._build_number_ui(schema);
+        } else if (type === 'text' || type === 'log') {
+            this._build_log_ui(schema);
+        } else if (type === 'percentage' || (type === 'number' && schema.min !== undefined && schema.max !== undefined)) {
+            this._build_gauge_ui(schema);
+        } else {
+            this._build_json_ui(schema);
+        }
+    }
+
+    _build_default_ui(first_data) {
+        if (typeof first_data === 'number') {
+            this._build_number_ui({ type: 'number' });
+        } else if (typeof first_data === 'string') {
+            this._build_log_ui({ type: 'text' });
+        } else {
+            this._build_json_ui({ type: 'object' });
+        }
+    }
+
+    _build_number_ui(schema) {
+        const val_div = new controls.div({
+            context: this.context,
+            class: 'value-display number-display'
+        });
+        this.content_container.add(val_div);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Value');
+        val_div.add(label);
+
+        const value_text = new controls.div({ context: this.context, class: 'value-text' });
+        value_text.add('--');
+        val_div.add(value_text);
+
+        this._update_handler = (data) => {
+            let val = data;
+            if (typeof data === 'object' && data.value !== undefined) val = data.value;
+            value_text.dom.innerText = String(val);
+        };
+    }
+
+    _build_log_ui(schema) {
+        const log_container = new controls.div({
+            context: this.context,
+            class: 'value-display log-display'
+        });
+        this.content_container.add(log_container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Log');
+        log_container.add(label);
+
+        const log_area = new controls.div({ context: this.context, class: 'log-area' });
+        log_container.add(log_area);
+
+        this._update_handler = (data) => {
+            const entry = document.createElement('div');
+            entry.className = 'log-entry';
+            let msg = data;
+            if (typeof data === 'object') msg = data.message || JSON.stringify(data);
+
+            entry.innerText = `[${new Date().toLocaleTimeString()}] ${msg}`;
+            log_area.dom.appendChild(entry);
+            log_area.dom.scrollTop = log_area.dom.scrollHeight;
+        };
+    }
+
+    _build_gauge_ui(schema) {
+        // Simple progress bar for now
+        const container = new controls.div({
+            context: this.context,
+            class: 'value-display gauge-display'
+        });
+        this.content_container.add(container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Gauge');
+        container.add(label);
+
+        const bar_bg = new controls.div({ context: this.context, class: 'progress-bg' });
+        const bar_fill = new controls.div({ context: this.context, class: 'progress-fill' });
+        bar_bg.add(bar_fill);
+        container.add(bar_bg);
+
+        const value_text = new controls.div({ context: this.context, class: 'value-text-small' });
+        container.add(value_text);
+
+        const min = schema.min || 0;
+        const max = schema.max || 100;
+
+        this._update_handler = (data) => {
+            let val = data;
+            if (typeof data === 'object' && data.value !== undefined) val = data.value;
+
+            const pct = Math.max(0, Math.min(100, ((val - min) / (max - min)) * 100));
+            bar_fill.dom.style.width = pct + '%';
+            value_text.dom.innerText = `${val} / ${max}`;
+        }
+    }
+
+    _build_json_ui(schema) {
+        const container = new controls.div({
+            context: this.context,
+            class: 'value-display json-display'
+        });
+        this.content_container.add(container);
+
+        const label = new controls.h3({ context: this.context });
+        label.add(schema.name || 'Data');
+        container.add(label);
+
+        const pre = new controls.pre({ context: this.context });
+        container.add(pre);
+
+        this._update_handler = (data) => {
+            pre.dom.innerText = JSON.stringify(data, null, 2);
+        }
+    }
+}
+
+module.exports = Auto_Observable_UI;

package/docs/books/admin-ui/01-introduction.md

@@ -0,0 +1,32 @@
+# Chapter 1: Introduction
+
+## Vision
+
+The Admin UI is the **go-to interface** for developers and operators to administer `jsgui3-server` instances. It should be:
+
+- **Instantaneous**: Zero setup required; just navigate to `/admin`
+- **Insightful**: Surface the internal state of the server in real-time
+- **Actionable**: Allow common admin tasks directly from the UI
+
+## Goals
+
+1. **Visibility into Observables**: If a server publishes an observable (e.g., for crawl progress, metrics), the Admin UI should display it automatically with an appropriate control.
+2. **Resource Browser**: List all registered resources (routes, publishers, static paths) with introspection.
+3. **Configuration Panel**: View and modify server configuration (where safe).
+4. **Performance Metrics**: Display throughput, active connections, memory usage.
+
+## Inspiration
+
+The design is inspired by:
+- Database admin tools (pgAdmin, phpMyAdmin)
+- Monitoring dashboards (Grafana, Kibana)
+- The jsgui3 Window control aesthetic
+
+## Target Experience
+
+A developer starts a jsgui3-server, then navigates to `http://localhost:PORT/admin`. They immediately see:
+- A sidebar listing all resources
+- A main panel showing the selected resource's details
+- Real-time updates for any observables
+
+No extra code required—the Admin UI is built into jsgui3-server and activates automatically.

package/docs/books/admin-ui/02-architecture.md

@@ -0,0 +1,92 @@
+# Chapter 2: Architecture
+
+## High-Level Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     jsgui3-server                            │
+│                                                              │
+│  ┌──────────────────┐   ┌────────────────┐                  │
+│  │ Admin UI Module  │◄──│ Server Router  │                  │
+│  │ (admin-ui/)      │   └───────┬────────┘                  │
+│  └────────┬─────────┘           │                           │
+│           │             ┌───────┴────────┐                  │
+│           ▼             │ Resource Pool  │                  │
+│  ┌─────────────────┐    │ (resources/)   │                  │
+│  │ Admin_Page      │    └───────┬────────┘                  │
+│  │ (client.js)     │            │                           │
+│  └────────┬────────┘    ┌───────┴────────┐                  │
+│           │             │ Publishers     │                  │
+│           ▼             │ (observables)  │                  │
+│  ┌─────────────────┐    └────────────────┘                  │
+│  │ Controls:       │                                        │
+│  │ - Resource_List │                                        │
+│  │ - Observable_   │                                        │
+│  │   Monitor       │                                        │
+│  │ - Config_Panel  │                                        │
+│  └─────────────────┘                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Module Structure
+
+```
+admin-ui/
+├── client.js         # Main client control (Admin_Page)
+├── server.js         # API routes for admin data
+├── controls/         # UI components
+│   ├── Resource_List.js
+│   ├── Observable_Monitor.js
+│   ├── Config_Panel.js
+│   └── Metrics_Dashboard.js
+└── styles/           # CSS modules
+    └── admin.css
+```
+
+## Key Patterns (from Window examples)
+
+1. **`client.js`** exports a jsgui module with controls registered on `jsgui.controls`
+2. **`server.js`** creates a `Server` instance, passes `Ctrl` and `src_path_client_js`
+3. Controls extend `Active_HTML_Document` for full-page apps
+4. CSS is defined as a static `.css` property on the control class
+5. `activate()` sets up client-side interactivity
+
+## Data Flow
+
+1. **Server Start** → Admin module registers `/admin` route
+2. **Client Request** → SSR renders Admin_Page with initial state
+3. **Activation** → Client connects to `/api/admin/resources` (SSE)
+4. **Updates** → Resource changes stream to client in real-time
+
+## Integration with `publish_observable`
+
+The Admin UI leverages the schema-aware observable system:
+- Server exposes `/api/admin/observables` listing all published observables
+- Each observable has a schema describing its data type
+- `Auto_Observable_UI` renders appropriate controls automatically
+
+## Server Lifecycle Events
+
+The server emits two distinct lifecycle events:
+
+| Event | Fired When | Use Case |
+|-------|------------|----------|
+| `ready` | Publishers/bundlers complete | Safe to call `server.start()`, publish routes |
+| `listening` | HTTP server bound to ports | Server accepting connections |
+
+**Example usage:**
+```javascript
+server.on('ready', () => {
+    // Publish observables and set up routes
+    server.publish_observable('/api/data', myObservable);
+    
+    // Now start accepting connections
+    server.start(port, (err) => {
+        console.log('Server running');
+    });
+});
+
+server.on('listening', () => {
+    console.log('Server accepting connections');
+});
+```