flexdesk 0.15.2 → 0.16.1

package/package.json

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

package/src/host/external_links.js

@@ -0,0 +1,94 @@
+/**
+ * external_links.js — links that leave the app open in the system browser.
+ *
+ * In a browser tab, `target="_blank"` and `window.open()` open a new tab, which
+ * is what everyone expects. In a native window (Photino, a webview) they open
+ * either nothing or a bare popup with no address bar and no way back. The host
+ * knows how to hand a URL to the OS (`host.shell.openExternal`); this routes
+ * the page's outbound links there.
+ *
+ * Without a `shell` capability it changes nothing, so an app can call it
+ * unconditionally at boot: in a browser tab it is a no-op.
+ */
+
+const SCHEMES = new Set(['http:', 'https:', 'mailto:']);
+
+/** The URL as an absolute URL when it is one we would send out, else null. */
+function outbound(href, base) {
+    let url;
+    try { url = new URL(String(href), base); } catch { return null; }
+    return SCHEMES.has(url.protocol) ? url : null;
+}
+
+/**
+ * Send external link clicks and `window.open` calls to `host.shell.openExternal`.
+ *
+ * A link goes out when it is http(s) or mailto AND it has `target="_blank"`,
+ * points to another origin, or is mailto. A same-origin link without a target
+ * is the app's own navigation and is left alone; a same-origin `_blank` goes
+ * out too, because in a native window the alternative is a bare popup. A
+ * handler that already called `preventDefault()` on the click keeps it.
+ *
+ * When `openExternal` resolves false (the native side refused it), the original
+ * `window.open` runs instead, so the click still does something.
+ *
+ * @param {object} opts
+ * @param {object} opts.host                  a Host; does nothing without `host.shell`
+ * @param {EventTarget} [opts.root=document]  where clicks are listened for
+ * @param {Window} [opts.win=window]          whose `open` is wrapped
+ * @returns {{ dispose: () => void }}
+ */
+export function routeExternalLinks({ host, root, win } = {}) {
+    const w = win ?? (typeof window !== 'undefined' ? window : null);
+    const r = root ?? (typeof document !== 'undefined' ? document : null);
+    const shell = host?.shell;
+    if (!shell || typeof shell.openExternal !== 'function' || !w || !r) return { dispose() {} };
+
+    const base = () => w.location?.href;
+    const origin = () => { try { return new URL(base()).origin; } catch { return null; } };
+    const nativeOpen = w.open;
+    const fallback = (href) => { try { nativeOpen?.call(w, href, '_blank', 'noopener'); } catch { /* blocked */ } };
+    const send = (href) => {
+        Promise.resolve()
+            .then(() => shell.openExternal(href))
+            .then((opened) => { if (opened !== true) fallback(href); }, () => fallback(href));
+    };
+
+    const onClick = (e) => {
+        if (e.defaultPrevented) return;
+        // Left click, or a middle click (auxclick): both open a new window.
+        if (e.type === 'click' ? e.button !== 0 : e.button !== 1) return;
+        const a = e.target?.closest?.('a[href]');
+        if (!a || a.hasAttribute('download')) return;
+        const url = outbound(a.getAttribute('href'), base());
+        if (!url) return;
+        const leaves = url.protocol === 'mailto:'
+            || (a.getAttribute('target') || '').toLowerCase() === '_blank'
+            || url.origin !== origin()
+            || e.button === 1;
+        if (!leaves) return;
+        e.preventDefault();
+        send(url.href);
+    };
+
+    const routedOpen = function open(href, target, features) {
+        const url = href == null ? null : outbound(href, base());
+        if (url && (url.protocol === 'mailto:' || url.origin !== origin())) {
+            send(url.href);
+            return null;
+        }
+        return nativeOpen.call(w, href, target, features);
+    };
+
+    r.addEventListener('click', onClick);
+    r.addEventListener('auxclick', onClick);
+    w.open = routedOpen;
+
+    return {
+        dispose() {
+            r.removeEventListener('click', onClick);
+            r.removeEventListener('auxclick', onClick);
+            if (w.open === routedOpen) w.open = nativeOpen;
+        },
+    };
+}

package/src/host/host.js

@@ -24,6 +24,9 @@ export const HOST_CONTRACT = Object.freeze({
     }),
     dialogs: Object.freeze({ required: Object.freeze(['saveFile']), optional: Object.freeze([]) }),
     state:   Object.freeze({ required: Object.freeze(['read', 'write']), optional: Object.freeze([]) }),
+    // `openExternal(url)` hands a web address to the OS's default browser and
+    // resolves true when it did. See external_links.js.
+    shell:   Object.freeze({ required: Object.freeze(['openExternal']), optional: Object.freeze([]) }),
 });
 
 /**
@@ -49,7 +52,7 @@ export function validateCapability(name, cap) {
  * 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
+ * @param {{ window?: object, dialogs?: object, state?: object, shell?: object }} caps
  * @returns {Readonly<object>} the Host
  */
 export function createHost(caps = {}) {

package/src/host/photino_host.js

@@ -106,6 +106,7 @@ export function createPhotinoTransport({ external, timeoutMs = 10000, onEvent =
  * @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
+ * @param {object|null} [opts.shell]    replace the shell capability, or `null` to leave it out
  * @returns {Readonly<object>} a Host, or NULL_HOST outside a Photino window
  */
 export function createPhotinoHost(opts = {}) {
@@ -182,6 +183,12 @@ export function createPhotinoHost(opts = {}) {
                 return r && typeof r === 'object' ? r : null;
             },
         },
+        shell: {
+            // True when the native side opened it in the system browser; false
+            // when it refused (a scheme it won't open, an older native side
+            // without the op): the caller falls back to window.open.
+            openExternal: async (url) => (await soft(false, 'shell', 'openExternal', String(url || ''))) === true,
+        },
         state: {
             async read(key) {
                 const v = await soft(null, 'state', 'read', key);

package/src/host/photino_host.md

@@ -40,6 +40,7 @@ host → page   {"event": "window.maximizedChanged", "value": true}
 | `window.startDrag` | `[]` | anything, **after mouse-up** | custom chrome only: the OS move loop (below) |
 | `window.startResize` | `[edge]`: `n` `s` `e` `w` `ne` `nw` `se` `sw` | anything, **after mouse-up** | custom chrome only: the OS size loop (below) |
 | `dialogs.saveFile` | `[{data, filename, kind}]` | see below | `ShowSaveFile(...)` + write |
+| `shell.openExternal` | `[url]` | `true` when opened | the OS's default browser (below) |
 | `state.read` | `[key]` | the stored value, or `null` | a file per key |
 | `state.write` | `[key, value]` | `true` | a file per key |
 
@@ -149,3 +150,20 @@ window.RegisterWebMessageReceivedHandler((sender, message) =>
 
 The handler runs on the window's thread; a save dialog shown from it is modal to
 the window, which is what you want.
+
+## Opening links in the system browser
+
+`shell.openExternal` takes one absolute URL and opens it with the OS's default
+handler: `Process.Start(new ProcessStartInfo(url) { UseShellExecute = true })`
+on Windows, `xdg-open` on Linux, `open` on macOS. Answer `true` once it has
+been handed over.
+
+**Refuse anything but `http:`, `https:` and `mailto:`** with `ok: false`. The
+URL comes from page content (a link in a record somebody else wrote), and a
+`file:` path or a custom protocol handed to the shell runs whatever the OS
+associates with it. Refused, the page falls back to `window.open`, which is
+no worse than a native side that doesn't have the op.
+
+The page side is `routeExternalLinks({ host })` (`external_links.js`). It
+sends external link clicks and `window.open` calls here; without a `shell`
+capability it changes nothing.