flexdesk 0.1.0

package/src/host/host.js

@@ -0,0 +1,69 @@
+/**
+ * host.js — the host port.
+ *
+ * The framework declares what it needs from its embedder. A Host is a bag of
+ * INDEPENDENTLY OPTIONAL capability objects:
+ *
+ *   - absent capability  => absent key (never a stub)
+ *   - present capability => must be complete (validated at boot)
+ *
+ * There is NO module-level default host and NO getHost(). Hosts are injected —
+ * a module singleton here would just be `window.pywebview` wearing a hat, and
+ * would make a second host (mock, browser tab, VS Code webview) impossible.
+ *
+ * Zero pywebview. Zero EcoAgent. See pywebview_host.js for the reference
+ * adapter that implements this port against the pywebview / HTTP transports.
+ */
+
+export const HOST_CONTRACT = Object.freeze({
+    window: Object.freeze({
+        required: Object.freeze(['chrome', 'minimize', 'close', 'isMaximized', 'setMaximized',
+                                 'isFullscreen', 'toggleFullscreen', 'getBounds', 'setBounds']),
+        optional: Object.freeze(['startNativeDrag']),
+    }),
+    dialogs: Object.freeze({ required: Object.freeze(['saveFile']), optional: Object.freeze([]) }),
+    state:   Object.freeze({ required: Object.freeze(['read', 'write']), optional: Object.freeze([]) }),
+});
+
+/**
+ * Validate ONE capability object. We validate the capability the adapter
+ * authored — a plain object literal with real closures — not the raw bridge:
+ * `index.html`'s browser-mode polyfill installs a `new Proxy({}, {get})` that
+ * returns a function for EVERY property name, so duck-typing the bridge is
+ * vacuously true and validates nothing. A Proxy cannot forge a missing key in
+ * an object literal.
+ *
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function validateCapability(name, cap) {
+    const spec = HOST_CONTRACT[name];
+    if (!spec) return { ok: false, missing: [`unknown capability '${name}'`] };
+    if (!cap || typeof cap !== 'object') return { ok: false, missing: [...spec.required] };
+    const missing = spec.required.filter((m) => typeof cap[m] !== 'function');
+    return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Validate + freeze a set of capabilities into a Host.
+ * Throws at boot on an incomplete capability — a half-wired host is a bug,
+ * and a bug at boot beats a silent degrade at click time.
+ *
+ * @param {{ window?: object, dialogs?: object, state?: object }} caps
+ * @returns {Readonly<object>} the Host
+ */
+export function createHost(caps = {}) {
+    const host = {};
+    for (const name of Object.keys(HOST_CONTRACT)) {
+        const cap = caps[name];
+        if (cap == null) continue;                       // legitimately absent
+        const v = validateCapability(name, cap);
+        if (!v.ok) {
+            throw new Error(`Host capability '${name}' is incomplete: missing ${v.missing.join(', ')}`);
+        }
+        host[name] = Object.freeze(cap);
+    }
+    return Object.freeze(host);
+}
+
+/** The zero-capability host. Every framework consumer MUST survive it. */
+export const NULL_HOST = createHost({});

package/src/host/pywebview_host.js

@@ -0,0 +1,133 @@
+/**
+ * pywebview_host.js — the REFERENCE host adapter.
+ *
+ * Knows pywebview. Knows NOTHING about EcoAgent: every domain fact (which
+ * bridge ref to use, where a state key lands on disk) arrives as a parameter.
+ * This is the adapter a standalone consumer copies; EcoAgent is just its first
+ * caller (see ui/js/bootstrap/app_bootstrap.js).
+ *
+ * It speaks to whatever `window.pywebview.api` currently is — the real
+ * pywebview bridge in the desktop app, or the `POST /api/<method>` Proxy
+ * polyfill that ui/index.html installs in --browser mode. Both transports are
+ * positional-on-the-wire, which is why setBounds() spreads its object back out
+ * into positional args.
+ */
+
+import { createHost } from './host.js';
+
+const FRAMELESS_BACKENDS = new Set(['edgechromium', 'mshtml']);
+
+/**
+ * Custom (frameless) window chrome — the min/max/close buttons, edge resize
+ * handles and drag-to-move top bar — only makes sense when our top bar IS the
+ * window's title bar. That holds on a native pywebview window the OS draws
+ * *without* decorations of its own: Windows (frameless). On Linux/macOS the
+ * window manager already draws a native title bar above our top bar, and in
+ * `--browser` mode the browser supplies its own chrome — in both cases the
+ * custom controls are a redundant second set, so we neither render nor wire
+ * them (which also stops us swallowing native F11 fullscreen and showing dead
+ * resize cursors at the window edges).
+ *
+ * Detection keys off the pywebview backend string, which is unambiguous: the
+ * browser-mode polyfill in index.html injects only `.api`, never `.platform`,
+ * so any `.platform` at all ⇒ running as a native pywebview app. The frameless
+ * (custom-title-bar) backends are the Windows WebViews — 'edgechromium' /
+ * 'mshtml'. Linux ('gtkwebkit2' / 'qtwebengine') and macOS ('cocoa') draw
+ * native decorations, so they return false. Verified live: WebKitGTK reports
+ * platform 'gtkwebkit2'.
+ */
+export function usesCustomWindowChrome() {
+    // Authoritative signal from the Python host: run_pywebview_mode() appends
+    // `?frameless=1` to the window URL exactly when it created a frameless native
+    // window (Windows). Prefer it over the backend sniff below because it's
+    // present at document parse — before pywebview finishes injecting
+    // `window.pywebview` (and before the browser-mode polyfill, which sets `.api`
+    // but no `.platform`, can clobber it). Reading the sniff at shell-build time
+    // otherwise races and the whole custom chrome silently fails to render.
+    try {
+        if (new URLSearchParams(window.location.search).get('frameless') === '1') {
+            return true;
+        }
+    } catch (_) { /* location unavailable (non-browser env) — fall through */ }
+    const platform = window.pywebview && window.pywebview.platform;
+    return !!platform && FRAMELESS_BACKENDS.has(platform);
+}
+
+/**
+ * Build a Host backed by the pywebview bridge.
+ *
+ * @param {object}  opts
+ * @param {{current: object|null}} [opts.bridgeRef]  LIVE ref to the bridge.
+ *        MUST be a ref, never a snapshot: `setupHostBridgeListener` mutates
+ *        `.current` when a late bridge arrives, and `resolveHostBridge` can
+ *        resolve `null` after its timeout. Snapshotting the bridge here would
+ *        freeze that null and reproduce as an intermittent boot failure.
+ * @param {(key: string) => string} [opts.resolvePath]  logical state key ->
+ *        storage path. THE domain seam: the framework only ever names keys
+ *        ('desktops', 'datatable_state'); the embedder decides where they land.
+ * @param {object} [opts.logger]
+ */
+export function createPywebviewHost({ bridgeRef = null, resolvePath = (k) => `${k}.json`, logger = console } = {}) {
+    const api = () => bridgeRef?.current ?? window.pywebview?.api ?? null;
+
+    const call = async (name, args = []) => {
+        const a = api();
+        if (!a || typeof a[name] !== 'function') return null;
+        try { return await a[name](...args); }
+        catch (e) { logger.warn?.('[host] call failed', name, e); return null; }
+    };
+
+    // Envelope unwrapping, in ONE place. Transcribed from the call sites this
+    // replaces, so app.py's catch-all `{ok: true}` reply (which carries no
+    // `maximized` key) still reads as false, exactly as it does today.
+    const okMax = (r) => Boolean(r && r.ok && r.maximized === true);
+    const okFs  = (r) => Boolean(r && r.ok && r.fullscreen);
+
+    // ALL THREE capabilities are ALWAYS advertised. Do NOT gate them on api()
+    // being non-null at construction time: the methods late-bind through the
+    // ref, and gating here would permanently strand a late-arriving bridge on
+    // the fallback paths (Blob download instead of the native save dialog).
+    return createHost({
+        window: {
+            chrome: () => (usesCustomWindowChrome() ? 'custom' : 'native'),
+            minimize: () => { void call('window_minimize'); },
+            close:    () => { void call('window_close'); },
+            isMaximized:      async () => okMax(await call('window_is_maximized')),
+            setMaximized:     async (on) => okMax(await call('window_set_maximized', [on])),
+            isFullscreen:     async () => okFs(await call('window_is_fullscreen')),
+            toggleFullscreen: async () => okFs(await call('window_toggle_fullscreen')),
+            async getBounds() {
+                const r = await call('window_get_bounds');
+                if (!r || !r.ok) return null;
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+            },
+            // POSITIONAL on the wire — both transports depend on it. Not async:
+            // this is a rAF hot path during a window drag/resize; nobody awaits.
+            setBounds({ x = null, y = null, width = null, height = null } = {}) {
+                void call('window_set_bounds', [x, y, width, height]);
+            },
+            startNativeDrag: async () => Boolean((await call('window_start_native_drag'))?.ok),
+        },
+        dialogs: {
+            // Resolves to null when the transport has no save_file_dialog behind it.
+            // Per host.js that is the contract for "unavailable", and every caller
+            // treats it exactly like an absent `dialogs` capability: fall back to a
+            // Blob download, never report a failed save. Covered by
+            // tests/ui/test_host_save_fallback.mjs.
+            saveFile: ({ data, filename, kind }) => call('save_file_dialog', [data, filename, kind]),
+        },
+        state: {
+            async read(key) {
+                const blob = await call('workspace_state_read', [{ path: resolvePath(key) }]);
+                if (!blob) return null;
+                try { return typeof blob === 'string' ? JSON.parse(blob) : blob; }
+                catch (e) { logger.warn?.('[host] bad JSON for state key', key, e); return null; }
+            },
+            async write(key, value) {
+                const r = await call('workspace_state_write',
+                                     [{ path: resolvePath(key), data: JSON.stringify(value) }]);
+                return r !== null;
+            },
+        },
+    });
+}

package/src/tiles/config_schema.js

@@ -0,0 +1,256 @@
+/**
+ * config_schema.js
+ *
+ * Configuration schema definitions for widget types.
+ * Defines field types, validation rules, and default values.
+ */
+
+/**
+ * Field type definitions for widget configuration.
+ */
+export const FieldTypes = {
+    TEXT: 'text',
+    NUMBER: 'number',
+    CHECKBOX: 'checkbox',
+    SELECT: 'select',
+    MULTISELECT: 'multiselect',
+    COLOR: 'color',
+    RANGE: 'range'
+};
+
+/**
+ * Validate a configuration value against its field schema.
+ * @param {any} value - Value to validate
+ * @param {Object} field - Field schema
+ * @returns {{valid: boolean, error?: string}} Validation result
+ */
+export function validateField(value, field) {
+    // Check required
+    if (field.required && (value == null || value === '')) {
+        return { valid: false, error: `${field.label} is required` };
+    }
+
+    // Type-specific validation
+    switch (field.type) {
+        case FieldTypes.NUMBER:
+        case FieldTypes.RANGE:
+            if (value != null && value !== '') {
+                const num = parseFloat(value);
+                if (isNaN(num)) {
+                    return { valid: false, error: `${field.label} must be a number` };
+                }
+                if (field.min != null && num < field.min) {
+                    return { valid: false, error: `${field.label} must be at least ${field.min}` };
+                }
+                if (field.max != null && num > field.max) {
+                    return { valid: false, error: `${field.label} must be at most ${field.max}` };
+                }
+            }
+            break;
+
+        case FieldTypes.SELECT:
+            if (field.required && !value) {
+                return { valid: false, error: `${field.label} must be selected` };
+            }
+            break;
+
+        case FieldTypes.MULTISELECT:
+            if (field.required && (!Array.isArray(value) || value.length === 0)) {
+                return { valid: false, error: `${field.label} must have at least one selection` };
+            }
+            break;
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Validate an entire configuration object against a schema.
+ * @param {Object} config - Configuration object
+ * @param {Object} schema - Schema with fields array
+ * @returns {{valid: boolean, errors: Object}} Validation result
+ */
+export function validateConfig(config, schema) {
+    const errors = {};
+    let valid = true;
+
+    if (!schema?.fields) {
+        return { valid: true, errors: {} };
+    }
+
+    schema.fields.forEach(field => {
+        const result = validateField(config[field.key], field);
+        if (!result.valid) {
+            errors[field.key] = result.error;
+            valid = false;
+        }
+    });
+
+    return { valid, errors };
+}
+
+/**
+ * Merge user config with defaults from schema.
+ * @param {Object} config - User configuration
+ * @param {Object} schema - Schema with fields array
+ * @returns {Object} Merged configuration
+ */
+export function mergeWithDefaults(config, schema) {
+    const result = { ...config };
+
+    if (schema?.fields) {
+        schema.fields.forEach(field => {
+            if (result[field.key] === undefined && field.default !== undefined) {
+                result[field.key] = field.default;
+            }
+        });
+    }
+
+    return result;
+}
+
+/**
+ * Get options for a select/multiselect field.
+ * Handles dynamic options (e.g., 'variables' which gets populated from data).
+ * @param {Object} field - Field schema
+ * @param {Object} data - Current data context
+ * @returns {Array<{value: string, label: string}>} Options array
+ */
+export function getFieldOptions(field, data) {
+    if (Array.isArray(field.options)) {
+        return field.options;
+    }
+
+    // Dynamic options based on string identifier
+    if (field.options === 'variables') {
+        return getVariableOptions(data);
+    }
+
+    if (field.options === 'namespaces') {
+        return getNamespaceOptions(data);
+    }
+
+    return [];
+}
+
+/**
+ * Format a raw analytics variable key into a user-friendly display label.
+ * Strips namespace prefixes, internal Godley patterns, and stock type suffixes.
+ *
+ * Examples:
+ *   "Agriculture.__SimpleStocks__::arable_land[State]" → "arable_land"
+ *   "Population.population"                             → "population"
+ *   "Banks::Assets[Cash]"                              → "Assets / Cash"
+ *   "my_variable"                                      → "my_variable"
+ *
+ * @param {string} name - Raw variable key from analytics
+ * @returns {string} Friendly display label
+ */
+export function formatVariableLabel(name) {
+    if (!name) return '';
+    let label = name;
+
+    // Strip namespace prefix: "Namespace.rest" → "rest"
+    const dotIdx = label.indexOf('.');
+    if (dotIdx > 0) {
+        label = label.slice(dotIdx + 1);
+    }
+
+    // Strip __SimpleStocks__:: or similar double-underscore sector prefixes
+    label = label.replace(/^__\w+__::/, '');
+
+    // Handle Godley stock pattern: "Sector::AccountType[Account]" → "AccountType / Account"
+    // But first strip [State] / [Rate] suffixes that are internal
+    label = label.replace(/\[State\]$/i, '');
+    label = label.replace(/\[Rate\]$/i, '');
+
+    // Clean up trailing empty brackets or colons from stripping
+    label = label.replace(/\[\]$/, '');
+
+    // Replace :: with readable separator
+    label = label.replace(/::/g, ' / ');
+
+    // Replace single colons used as separators with underscore
+    label = label.replace(/:/g, '_');
+
+    // Clean up any double spaces or leading/trailing whitespace
+    return label.replace(/\s{2,}/g, ' ').trim();
+}
+
+/**
+ * Get variable options from data.
+ * @param {Object} data - Analytics data
+ * @returns {Array<{value: string, label: string, category?: string}>} Variable options
+ */
+export function getVariableOptions(data) {
+    const options = [];
+
+    if (!data) return options;
+
+    // Add stocks
+    if (data.stocks) {
+        Object.keys(data.stocks).forEach(name => {
+            options.push({
+                value: name,
+                label: formatVariableLabel(name),
+                category: 'Stocks'
+            });
+        });
+    }
+
+    // Add flows
+    if (data.flows) {
+        Object.keys(data.flows).forEach(name => {
+            options.push({
+                value: name,
+                label: formatVariableLabel(name),
+                category: 'Flows'
+            });
+        });
+    }
+
+    // Add indicators
+    if (data.indicators) {
+        Object.keys(data.indicators).forEach(name => {
+            options.push({
+                value: name,
+                label: formatVariableLabel(name),
+                category: 'Indicators'
+            });
+        });
+    }
+
+    return options;
+}
+
+/**
+ * Extract unique namespace names from variable keys in data.
+ * Stock keys follow the pattern "Namespace.Sector::Type[Account]".
+ * @param {Object} data - Analytics data
+ * @returns {Array<{value: string, label: string}>}
+ */
+export function getNamespaceOptions(data) {
+    const namespaces = new Set();
+    const sources = [data?.stocks, data?.flows, data?.indicators];
+    for (const source of sources) {
+        if (!source) continue;
+        for (const key of Object.keys(source)) {
+            const dotIdx = key.indexOf('.');
+            if (dotIdx > 0) {
+                namespaces.add(key.slice(0, dotIdx));
+            }
+        }
+    }
+    if (namespaces.size === 0) namespaces.add('Main');
+    return Array.from(namespaces).sort().map(ns => ({ value: ns, label: ns }));
+}
+
+export default {
+    FieldTypes,
+    validateField,
+    validateConfig,
+    mergeWithDefaults,
+    getFieldOptions,
+    getVariableOptions,
+    formatVariableLabel
+};