flexdesk 0.12.1 → 0.14.0

package/package.json

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

package/src/charts/chart_types.js

@@ -566,12 +566,17 @@ export function buildLegendLayout(position) {
  *   `yAxisId` matches an axis id in sp.yAxes[].id; omitted → first axis.
  * @param {Array<{x0:number, x1:number, label?:string, color?:string, opacity?:number, labelY?:number, labelColor?:string}>} [opts.shadedBands]
  *   Vertical stripes (rectangles spanning full y range) to mark policy/recession periods.
+ * @param {Array<{x:(number|string|Date), label?:string, color?:string, lineStyle?:string, lineWidth?:number, labelY?:number}>} [opts.verticalLines]
+ *   Vertical markers at one x — a "today" line on a burndown. Drawn full height
+ *   (`yref: 'paper'`), after the reference lines, so a call without them builds
+ *   exactly what it built before they existed. `x` is in the x axis's own units:
+ *   a number, a category, or a date string/Date on a date axis.
  * @param {Object<string,string>} [opts.yRefByAxisId]
  *   Mapping from subplot yAxes[i].id → Plotly yref ('y', 'y2', ...).
  * @returns {{shapes: Array, annotations: Array}}
  */
 export function buildOverlayShapes(opts = {}) {
-    const { referenceLines = [], shadedBands = [], yRefByAxisId = {} } = opts;
+    const { referenceLines = [], shadedBands = [], verticalLines = [], yRefByAxisId = {} } = opts;
     const shapes = [];
     const annotations = [];
     const dashMap = { solid: 'solid', dashed: 'dash', dotted: 'dot', dashdot: 'dashdot' };
@@ -643,6 +648,40 @@ export function buildOverlayShapes(opts = {}) {
         }
     }
 
+    for (const mark of verticalLines) {
+        // `0` is a real x, so the test is null/undefined/NaN — never truthiness.
+        if (mark == null || mark.x == null || (typeof mark.x === 'number' && !Number.isFinite(mark.x))) continue;
+        const color = mark.color || 'rgba(255, 200, 0, 0.75)';
+        shapes.push({
+            type: 'line',
+            xref: 'x',
+            yref: 'paper',
+            x0: mark.x,
+            x1: mark.x,
+            y0: 0,
+            y1: 1,
+            line: {
+                color,
+                width: mark.lineWidth ?? 1.5,
+                dash: dashMap[mark.lineStyle || 'dashed'] || 'dash',
+            },
+            layer: 'above',
+        });
+        if (mark.label) {
+            annotations.push({
+                x: mark.x,
+                y: mark.labelY ?? 1.0,
+                xref: 'x',
+                yref: 'paper',
+                text: mark.label,
+                showarrow: false,
+                font: { size: 10, color },
+                xanchor: 'left',
+                yanchor: 'bottom',
+            });
+        }
+    }
+
     return { shapes, annotations };
 }
 

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.