flexdesk 0.13.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.13.0",
+    "version": "0.14.1",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/flow/kit/dom.js

@@ -154,6 +154,10 @@ export function openPopover({ anchor, content, label, className = '', onClose =
         handle.close('escape');
     };
     const onResize = () => place();
+    // Placed before its content is drawn — a picker fills its list after this
+    // returns — so it is placed again whenever its size changes, or it would
+    // run past the window's edge.
+    const sized = typeof ResizeObserver === 'function' ? new ResizeObserver(() => place()) : null;
 
     const handle = {
         el: pop,
@@ -168,6 +172,7 @@ export function openPopover({ anchor, content, label, className = '', onClose =
             document.removeEventListener('mousedown', onPress, true);
             pop.removeEventListener('keydown', onKey);
             window.removeEventListener('resize', onResize);
+            sized?.disconnect();
             pop.remove();
             if (ACTIVE === handle) ACTIVE = null;
             // Focus that LEFT the popover (a Tab out of it) is going somewhere the
@@ -185,6 +190,7 @@ export function openPopover({ anchor, content, label, className = '', onClose =
     }, 0);
     pop.addEventListener('keydown', onKey);
     window.addEventListener('resize', onResize);
+    sized?.observe(pop);
     place();
     (focus || pop).focus?.({ preventScroll: true });
     return handle;

package/src/host/photino_host.js

@@ -0,0 +1,176 @@
+/**
+ * photino_host.js — the host port over a Photino.NET window.
+ *
+ * Photino gives the page exactly two things: `window.external.sendMessage(text)`
+ * and `window.external.receiveMessage(callback)`. Strings in, strings out, no
+ * replies. This adapter puts a request/reply protocol over them, matched by id:
+ *
+ *   page → host   {"id": 7, "cap": "window", "op": "setBounds", "args": [{"x":0,"y":0,"width":1200,"height":800}]}
+ *   host → page   {"id": 7, "ok": true,  "value": null}
+ *   host → page   {"id": 8, "ok": false, "error": "no such op"}
+ *   host → page   {"event": "window.maximizedChanged", "value": true}      // unsolicited, no id
+ *
+ * and offers the port's `window`, `dialogs` and `state` capabilities on top.
+ * The C# side — one dispatcher on the window's web-message handler, every op
+ * with its args and reply — is documented in `photino_host.md` beside this file.
+ *
+ * Like pywebview_host.js it knows the transport and NOTHING about the app: an
+ * embedder that keeps some capability elsewhere (BugDesk keeps `state` on its
+ * own server) passes that capability in, or `null` to leave it out.
+ *
+ * In a browser tab there is no `window.external.sendMessage`, and
+ * createPhotinoHost() returns NULL_HOST — the fallback every FlexDesk consumer
+ * already has to survive.
+ */
+
+import { createHost, NULL_HOST } from './host.js';
+
+/** True when `ext` (default: `window.external`) is a Photino bridge. */
+export function isPhotinoWindow(ext = (typeof window !== 'undefined' ? window.external : undefined)) {
+    return !!ext && typeof ext.sendMessage === 'function' && typeof ext.receiveMessage === 'function';
+}
+
+/**
+ * The bare request/reply layer. `call(cap, op, ...args)` sends one request and
+ * resolves with the reply's `value` (`request(cap, op, args, {wait})` is the
+ * same with a timeout of its own). It REJECTS when the host answers
+ * `ok: false` (with the host's error) and when no reply arrives within
+ * `timeoutMs`. A reply for an id nobody is waiting on, a message that is not
+ * JSON, and anything that is neither a reply nor an event are dropped.
+ *
+ * @param {object} opts
+ * @param {{sendMessage: Function, receiveMessage: Function}} opts.external
+ * @param {number}  [opts.timeoutMs=10000]
+ * @param {(name: string, value: any) => void} [opts.onEvent]  id-less `{event, value}` messages
+ * @param {object}  [opts.logger]
+ */
+export function createPhotinoTransport({ external, timeoutMs = 10000, onEvent = null, logger = console }) {
+    const pending = new Map();
+    let seq = 0;
+    external.receiveMessage((text) => {
+        let m;
+        try { m = typeof text === 'string' ? JSON.parse(text) : text; } catch { return; }
+        if (!m || typeof m !== 'object') return;
+        if (m.id == null) {
+            if (typeof m.event === 'string' && onEvent) {
+                try { onEvent(m.event, m.value); }
+                catch (e) { logger.warn?.('[host] photino event handler failed', m.event, e); }
+            }
+            return;
+        }
+        const p = pending.get(m.id);
+        if (!p) return;
+        pending.delete(m.id);
+        clearTimeout(p.timer);
+        if (m.ok) p.resolve(m.value === undefined ? null : m.value);
+        else p.reject(new Error(m.error || `${p.what}: refused by the host`));
+    });
+    // `wait` is this request's timeout in ms; 0 waits for as long as it takes.
+    const request = (cap, op, args = [], { wait = timeoutMs } = {}) => new Promise((resolve, reject) => {
+        const id = ++seq;
+        const what = `${cap}.${op}`;
+        const timer = wait > 0 ? setTimeout(() => {
+            if (pending.delete(id)) reject(new Error(`${what}: no answer from the host within ${wait} ms`));
+        }, wait) : null;
+        pending.set(id, { resolve, reject, timer, what });
+        try {
+            external.sendMessage(JSON.stringify({ id, cap, op, args }));
+        } catch (e) {
+            pending.delete(id);
+            clearTimeout(timer);
+            reject(e);
+        }
+    });
+    const call = (cap, op, ...args) => request(cap, op, args);
+    return { call, request, pending: () => pending.size };
+}
+
+/**
+ * Build a Host backed by a Photino window.
+ *
+ * The capability methods follow pywebview_host.js's contract, so a consumer
+ * cannot tell the two apart: they DEGRADE instead of rejecting. A failed query
+ * reads as false / null, a failed fire-and-forget is logged, and a save that
+ * the host refused or never answered resolves `null` — the host.js meaning of
+ * "unavailable", which every caller turns into a Blob download.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.external=window.external]  the Photino bridge (a fake one in tests)
+ * @param {number} [opts.timeoutMs=10000]
+ * @param {(name: string, value: any) => void} [opts.onEvent]
+ * @param {object} [opts.logger=console]
+ * @param {object|null} [opts.window]   replace the window capability, or `null` to leave it out
+ * @param {object|null} [opts.dialogs]  replace the dialogs capability, or `null` to leave it out
+ * @param {object|null} [opts.state]    replace the state capability, or `null` to leave it out
+ * @returns {Readonly<object>} a Host, or NULL_HOST outside a Photino window
+ */
+export function createPhotinoHost(opts = {}) {
+    const {
+        external = (typeof window !== 'undefined' ? window.external : undefined),
+        timeoutMs = 10000,
+        onEvent = null,
+        logger = console,
+    } = opts;
+    if (!isPhotinoWindow(external)) return NULL_HOST;
+
+    const { call, request } = createPhotinoTransport({ external, timeoutMs, onEvent, logger });
+    const warn = (cap, op, e) => logger.warn?.('[host] photino call failed', `${cap}.${op}`, e);
+    const soft = async (fallback, cap, op, ...args) => {
+        try { return await call(cap, op, ...args); }
+        catch (e) { warn(cap, op, e); return fallback; }
+    };
+    const fire = (cap, op, ...args) => { void soft(null, cap, op, ...args); };
+
+    const defaults = {
+        window: {
+            // Photino draws a decorated, native window on every OS: FlexDesk's
+            // own min/max/close buttons would be a second set.
+            chrome: () => 'native',
+            minimize: () => { fire('window', 'minimize'); },
+            close: () => { fire('window', 'close'); },
+            isMaximized: async () => (await soft(false, 'window', 'isMaximized')) === true,
+            setMaximized: async (on) => (await soft(false, 'window', 'setMaximized', !!on)) === true,
+            isFullscreen: async () => (await soft(false, 'window', 'isFullscreen')) === true,
+            toggleFullscreen: async () => (await soft(false, 'window', 'toggleFullscreen')) === true,
+            async getBounds() {
+                const b = await soft(null, 'window', 'getBounds');
+                if (!b || typeof b !== 'object') return null;
+                return { x: b.x, y: b.y, width: b.width, height: b.height };
+            },
+            // Not async, like pywebview's: a rAF hot path during a drag; nobody awaits.
+            setBounds({ x = null, y = null, width = null, height = null } = {}) {
+                fire('window', 'setBounds', { x, y, width, height });
+            },
+        },
+        dialogs: {
+            // `{ok: true, path}` | `{ok: false, cancelled: true}` | `{ok: false, error}`,
+            // or null when the host refused: fall back to a download. NO TIMEOUT —
+            // the dialog is open for as long as the user takes, and giving up on it
+            // would download the file a second time behind the dialog.
+            async saveFile({ data, filename, kind } = {}) {
+                let r = null;
+                try { r = await request('dialogs', 'saveFile', [{ data, filename, kind }], { wait: 0 }); }
+                catch (e) { warn('dialogs', 'saveFile', e); }
+                return r && typeof r === 'object' ? r : null;
+            },
+        },
+        state: {
+            async read(key) {
+                const v = await soft(null, 'state', 'read', key);
+                if (typeof v !== 'string') return v ?? null;
+                try { return JSON.parse(v); }
+                catch (e) { logger.warn?.('[host] bad JSON for state key', key, e); return null; }
+            },
+            async write(key, value) {
+                return (await soft(false, 'state', 'write', key, value)) !== false;
+            },
+        },
+    };
+
+    const caps = {};
+    for (const name of Object.keys(defaults)) {
+        if (!(name in opts)) caps[name] = defaults[name];
+        else if (opts[name] != null) caps[name] = opts[name];
+    }
+    return createHost(caps);
+}

package/src/host/photino_host.md

@@ -0,0 +1,98 @@
+# The Photino host: the C# side
+
+`createPhotinoHost()` (`photino_host.js`) talks to a Photino.NET window over
+`window.external.sendMessage` / `receiveMessage`. This is what the window has to
+answer. One handler on the window's web messages does all of it.
+
+## Messages
+
+```
+page → host   {"id": 7, "cap": "window", "op": "setBounds", "args": [{"x":0,"y":0,"width":1200,"height":800}]}
+host → page   {"id": 7, "ok": true,  "value": null}
+host → page   {"id": 8, "ok": false, "error": "unknown request window.bogus"}
+host → page   {"event": "window.maximizedChanged", "value": true}
+```
+
+- Every request gets exactly one reply with the same `id`. A request that gets
+  none is given up after 10 s (`timeoutMs`). `dialogs.saveFile` is the
+  exception: the page waits for it without a timeout, because the dialog stays
+  open as long as the user takes. Always answer it.
+- `ok: false` means "I can't": the adapter logs it and degrades, exactly as it
+  does with pywebview. Use it for unknown ops and for failures.
+- A message with no `id` and an `event` name is an event. The adapter hands it
+  to the `onEvent(name, value)` option; it never answers a request.
+- Anything that is not JSON, or is a reply to an id nobody waits for, is
+  ignored, so the window may share the channel with other messages.
+
+## Ops
+
+| `cap.op` | `args` | reply `value` | Photino |
+|---|---|---|---|
+| `window.minimize` | `[]` | anything | `Minimized = true` |
+| `window.close` | `[]` | anything | `Close()` |
+| `window.isMaximized` | `[]` | `bool` | `Maximized` |
+| `window.setMaximized` | `[bool]` | `bool`, the state now | `Maximized = on` |
+| `window.isFullscreen` | `[]` | `bool` | `FullScreen` |
+| `window.toggleFullscreen` | `[]` | `bool`, the state now | `FullScreen = !FullScreen` |
+| `window.getBounds` | `[]` | `{x, y, width, height}` | `Location`, `Size` |
+| `window.setBounds` | `[{x, y, width, height}]`, any of them `null` = leave alone | anything | `Location`, `Size` |
+| `dialogs.saveFile` | `[{data, filename, kind}]` | see below | `ShowSaveFile(...)` + write |
+| `state.read` | `[key]` | the stored value, or `null` | a file per key |
+| `state.write` | `[key, value]` | `true` | a file per key |
+
+`window.chrome()` is answered by the adapter itself (`'native'`): Photino draws a
+native title bar, so FlexDesk draws no buttons of its own. `startNativeDrag` is
+not offered.
+
+**`dialogs.saveFile`.** `kind` is the file type the caller is saving, `'csv'`
+or `'png'` today. `data` is the file's text for `csv` and the file's bytes,
+base64, for `png` (decode it before writing). Show a save dialog suggesting
+`filename`, write the file, and reply with one of:
+
+```
+{"ok": true,  "path": "C:\\Users\\me\\Documents\\rows.csv"}      saved
+{"ok": false, "cancelled": true}                                the user cancelled: nothing is said
+{"ok": false, "error": "Access to the path is denied."}        shown to the user
+```
+
+as the reply's `value` (the envelope's own `ok` stays `true`). A reply with the
+envelope's `ok: false`, or none at all, makes `saveFile` resolve `null`, and the
+caller downloads the file the browser way instead.
+
+**`state`.** `value` is any JSON value; store it and give it back unchanged. A
+string value that holds JSON is parsed on the way back, for hosts that store
+the text.
+
+## A dispatcher
+
+```csharp
+window.RegisterWebMessageReceivedHandler((sender, message) =>
+{
+    var w = (PhotinoWindow)sender!;
+    using var doc = JsonDocument.Parse(message);
+    var req = doc.RootElement;
+    if (!req.TryGetProperty("id", out var id)) return;
+    var args = req.GetProperty("args");
+    string reply;
+    try
+    {
+        object? value = (req.GetProperty("cap").GetString(), req.GetProperty("op").GetString()) switch
+        {
+            ("window", "isMaximized") => w.Maximized,
+            ("window", "setMaximized") => w.Maximized = args[0].GetBoolean(),
+            ("window", "getBounds") => new { x = w.Left, y = w.Top, width = w.Width, height = w.Height },
+            // ... the rest of the table
+            var (c, o) => throw new InvalidOperationException($"unknown request {c}.{o}"),
+        };
+        reply = JsonSerializer.Serialize(new { id = JsonSerializer.Deserialize<object>(id.GetRawText()), ok = true, value });
+    }
+    catch (Exception ex)
+    {
+        reply = JsonSerializer.Serialize(new { id = JsonSerializer.Deserialize<object>(id.GetRawText()), ok = false, error = ex.Message });
+    }
+    w.SendWebMessage(reply);
+});
+```
+
+The handler runs on the window's thread; a save dialog shown from it is modal to
+the window, which is what you want.

package/src/tiles/chart_tiles.js

@@ -528,9 +528,22 @@ export class ChartTile extends TileBase {
         try {
             const P = await ensurePlotly();
             const uri = await P.toImage(this._plotEl, { format: 'png', scale: 2 });
+            const filename = `${slug(this.config.title || this.constructor.TITLE)}.png`;
+            // The native Save dialog when the host has one (a desktop window).
+            // `saveFile` answers null when there is no dialog behind it, which
+            // means "download it yourself", not a failed save.
+            const dialogs = this.host?.dialogs;
+            const result = dialogs
+                ? await dialogs.saveFile({ data: uri.split(',')[1], filename, kind: 'png' })
+                : null;
+            if (result) {
+                if (result.ok) this._notify('Download', `Chart saved to ${result.path}`, 'success');
+                else if (!result.cancelled) this._notify('Download failed', result.error || 'The image could not be saved', 'error');
+                return;
+            }
             const a = document.createElement('a');
             a.href = uri;
-            a.download = `${slug(this.config.title || this.constructor.TITLE)}.png`;
+            a.download = filename;
             a.click();
         } catch (err) {
             this._notify('Download failed', `The image could not be made: ${err?.message || err}`, 'error');

package/src/tiling/bottom_panel_tabs.js

@@ -0,0 +1,201 @@
+/**
+ * ══ THE BOTTOM PANEL'S TAB HOST ══════════════════════════════════════════
+ *
+ * The `.twm-bp*` CSS shipped for a long time with no JS behind it, and two
+ * embedders wrote the same strip on top of it: bugdesk (Alerts and Changes,
+ * with a count on each tab) and Tables (SQL, Database, History, Activity, each
+ * pane with storage of its own). This is the two merged, so the third embedder
+ * writes none of it (FlexDesk STORY-0018).
+ *
+ *     const tabs = createBottomPanelTabs(host, {
+ *         panes: [{ id: 'alerts', label: 'Alerts', eager: true, mount(el, store, api) { … } }],
+ *         remember: { read: () => saved, write: (id) => … },
+ *         eventBus,
+ *     });
+ *     tabs.setBadge('alerts', 3, 'warning');
+ *     eventBus.emit('bottompanel:show', { tab: 'alerts' });
+ *
+ * A PANE is `{ id, label, mount(el, store, api), eager? }`. `mount` answers an
+ * instance, or nothing; the host calls the instance's `onShow()` each time its
+ * tab comes to the front, `persist()` before the panel goes, `destroy()` when
+ * it is gone for good. A pane is mounted the first time it is shown — or at
+ * once, with `eager: true`, when its tab carries a count that must be right
+ * before anyone opens it (bugdesk's Alerts). Those two mount INSIDE this call,
+ * before it has answered: a pane reaches the host through its `api` argument
+ * (`api.setBadge(…)`), never through the variable the call is being assigned to.
+ *
+ * `store` is the pane's OWN persistence, from the embedder's `store(pane)`, or
+ * null. COLLAPSING A PANEL DESTROYS ITS CONTENT (the tile leaf goes, and its
+ * GC calls `destroy`), so a pane holding unsaved state — half-written SQL —
+ * saves it itself; the host cannot know what that is.
+ *
+ * `remember` keeps the tab last in front, in whatever store the embedder has
+ * (bugdesk: localStorage; Tables: its server blob, beside the panel's height).
+ * Its `read` may answer a promise. A remembered tab no longer offered falls
+ * back to the first; and A TAB A CALLER ALREADY CHOSE WINS — the read is a
+ * round trip, and a panel opened BY a button for one tab used to be put back
+ * on the remembered one when the read answered (Tables, 2026-10-12).
+ *
+ * `bottompanel:show` on the embedder's bus, with `{ tab }`, brings a tab to the
+ * front (a toast's "+N more" asks for Alerts). The host only selects; whether
+ * the panel itself is open is the embedder's (a tile it toggles), so the bus
+ * event is the embedder's to hear too.
+ *
+ * The strip is never rebuilt: a select toggles classes on the same buttons, so
+ * a click that lands while a tab is being selected keeps its target.
+ */
+
+/** Badge levels, worst last. Any other value draws the neutral badge. */
+export const BADGE_LEVELS = Object.freeze(['info', 'warning', 'alert']);
+
+/**
+ * @param {HTMLElement} container
+ * @param {object}   opts
+ * @param {Array}    opts.panes      `{ id, label, mount(el, store, api), eager? }`
+ * @param {object}  [opts.remember]  `{ read(): id|Promise<id>, write(id) }`
+ * @param {Function}[opts.store]     `(pane) => { read, write } | null` — a pane's own storage
+ * @param {object}  [opts.eventBus]  hears `bottompanel:show`
+ * @param {Function}[opts.onSelect]  `(id, pane)` — e.g. the tile's title
+ * @param {string}  [opts.initial]   the tab in front before `remember` answers
+ */
+export function createBottomPanelTabs(container, {
+    panes = [], remember = null, store = null, eventBus = null, onSelect = null, initial = null,
+} = {}) {
+    const doc = container.ownerDocument;
+    const root = doc.createElement('div');
+    root.className = 'twm-bp';
+    const strip = doc.createElement('div');
+    strip.className = 'twm-bp__tabs';
+    strip.setAttribute('role', 'tablist');
+    const body = doc.createElement('div');
+    body.className = 'twm-bp__body';
+    root.append(strip, body);
+    container.appendChild(root);
+
+    const byId = new Map(panes.map((pane) => [pane.id, pane]));
+    const tabs = new Map();
+    const mounted = new Map();
+    let active = null;
+    let chosen = false;
+    let destroyed = false;
+
+    for (const pane of panes) {
+        const tab = doc.createElement('button');
+        tab.type = 'button';
+        tab.className = 'twm-bp__tab';
+        tab.dataset.pane = pane.id;
+        tab.setAttribute('role', 'tab');
+        tab.setAttribute('aria-selected', 'false');
+        const label = doc.createElement('span');
+        label.className = 'twm-bp__label';
+        label.textContent = pane.label;
+        const badge = doc.createElement('span');
+        badge.className = 'twm-bp__badge';
+        badge.hidden = true;
+        tab.append(label, badge);
+        tab.addEventListener('click', () => api.select(pane.id));
+        strip.appendChild(tab);
+        tabs.set(pane.id, tab);
+    }
+
+    function mount(id) {
+        if (mounted.has(id)) return mounted.get(id);
+        const pane = byId.get(id);
+        const el = doc.createElement('div');
+        el.className = 'twm-bp-pane';
+        el.dataset.pane = id;
+        el.setAttribute('role', 'tabpanel');
+        el.hidden = id !== active;
+        body.appendChild(el);
+        const entry = { el, instance: null };
+        mounted.set(id, entry);
+        // ONE PANE THAT THROWS IS ONE EMPTY TAB, not a dead panel: the strip
+        // and every other pane go on working.
+        try {
+            entry.instance = pane.mount?.(el, store ? store(pane) : null, api) ?? null;
+        } catch (err) {
+            console.error(`[bottom-panel] pane "${id}" failed to mount`, err);
+        }
+        return entry;
+    }
+
+    function show(id) {
+        if (destroyed || !byId.has(id)) return false;
+        active = id;
+        for (const [key, tab] of tabs) {
+            const on = key === id;
+            tab.classList.toggle('twm-bp__tab--on', on);
+            tab.setAttribute('aria-selected', String(on));
+        }
+        for (const [key, entry] of mounted) entry.el.hidden = key !== id;
+        mount(id).instance?.onShow?.();
+        onSelect?.(id, byId.get(id));
+        return true;
+    }
+
+    const api = {
+        root,
+        /** Bring a tab to the front, and remember it. */
+        select(id) {
+            if (!show(id)) return;
+            chosen = true;
+            try { remember?.write?.(id); } catch { /* storage refused: not ours to fix */ }
+        },
+        /** The tab in front, or null. */
+        active: () => active,
+        /** `count` on a tab, coloured by `level`; nothing at zero. */
+        setBadge(id, count, level = null) {
+            const badge = tabs.get(id)?.querySelector('.twm-bp__badge');
+            if (!badge) return;
+            const n = Number(count) || 0;
+            badge.hidden = n <= 0;
+            badge.textContent = n > 99 ? '99+' : String(Math.max(n, 0));
+            badge.className = 'twm-bp__badge'
+                + (BADGE_LEVELS.includes(level) ? ` twm-bp__badge--${level}` : '');
+        },
+        /** A mounted pane's live instance, or null — how one tab hands work to
+         *  another. `select` it first, which mounts it. */
+        instance: (id) => mounted.get(id)?.instance ?? null,
+        /** The panel is on screen again (its tile re-mounted): tell the pane in front. */
+        reshow() {
+            if (active) mounted.get(active)?.instance?.onShow?.();
+        },
+        /** Before the panel is torn down: every mounted pane saves. */
+        async persist() {
+            for (const entry of mounted.values()) await entry.instance?.persist?.();
+        },
+        /** Gone for good: panes save, then are destroyed; the bus is let go. */
+        async destroy() {
+            if (destroyed) return;
+            await api.persist();
+            destroyed = true;
+            try { subscription?.dispose?.(); } catch { /* bus gone */ }
+            for (const entry of mounted.values()) {
+                try { entry.instance?.destroy?.(); } catch (err) {
+                    console.warn('[bottom-panel] pane destroy failed', err);
+                }
+            }
+            mounted.clear();
+            root.remove();
+        },
+    };
+
+    for (const pane of panes) if (pane.eager) mount(pane.id);
+
+    const subscription = eventBus?.on?.('bottompanel:show',
+        (payload) => api.select(payload?.tab ?? panes[0]?.id)) ?? null;
+
+    show(byId.has(initial) ? initial : panes[0]?.id);
+
+    if (remember?.read) {
+        Promise.resolve()
+            .then(() => remember.read())
+            .then((saved) => {
+                if (chosen || destroyed) return;
+                if (byId.has(saved)) show(saved);
+            })
+            .catch(() => { /* nothing remembered */ });
+    }
+
+    return api;
+}